diff options
Diffstat (limited to 'gcc/doc')
| -rw-r--r-- | gcc/doc/analyzer.texi | 36 | ||||
| -rw-r--r-- | gcc/doc/avr-mmcu.texi | 6 | ||||
| -rw-r--r-- | gcc/doc/cfg.texi | 10 | ||||
| -rw-r--r-- | gcc/doc/extend.texi | 4313 | ||||
| -rw-r--r-- | gcc/doc/gcc.texi | 1 | ||||
| -rw-r--r-- | gcc/doc/gcov.texi | 2 | ||||
| -rw-r--r-- | gcc/doc/gm2.texi | 13 | ||||
| -rw-r--r-- | gcc/doc/implement-c.texi | 248 | ||||
| -rw-r--r-- | gcc/doc/install.texi | 33 | ||||
| -rw-r--r-- | gcc/doc/invoke.texi | 1418 | ||||
| -rw-r--r-- | gcc/doc/libgdiagnostics/topics/compatibility.rst | 221 | ||||
| -rw-r--r-- | gcc/doc/libgdiagnostics/topics/diagnostic-manager.rst | 42 | ||||
| -rw-r--r-- | gcc/doc/libgdiagnostics/topics/graphs.rst | 197 | ||||
| -rw-r--r-- | gcc/doc/libgdiagnostics/topics/index.rst | 2 | ||||
| -rw-r--r-- | gcc/doc/libgdiagnostics/topics/logical-locations.rst | 56 | ||||
| -rw-r--r-- | gcc/doc/libgdiagnostics/tutorial/02-physical-locations.rst | 11 | ||||
| -rw-r--r-- | gcc/doc/md.texi | 19 | ||||
| -rw-r--r-- | gcc/doc/riscv-ext.texi | 717 | ||||
| -rw-r--r-- | gcc/doc/sourcebuild.texi | 40 | ||||
| -rw-r--r-- | gcc/doc/standards.texi | 42 | ||||
| -rw-r--r-- | gcc/doc/tm.texi | 4 | ||||
| -rw-r--r-- | gcc/doc/trouble.texi | 8 | ||||
| -rw-r--r-- | gcc/doc/ux.texi | 7 |
23 files changed, 4481 insertions, 2965 deletions
diff --git a/gcc/doc/analyzer.texi b/gcc/doc/analyzer.texi index 755db7c..4efba4d 100644 --- a/gcc/doc/analyzer.texi +++ b/gcc/doc/analyzer.texi @@ -619,6 +619,25 @@ python-xdot) @item @code{-fdump-analyzer-exploded-nodes-2} which dumps a @file{SRC.eg.txt} file containing the full @code{exploded_graph}. +@item @code{-fdiagnostics-add-output=experimental-html:show-state-diagrams=yes} +which writes out the diagnostics in HTML form, and generates SVG state +diagrams visualizing the state of memory at each event (inspired by the +"ddd" debugger). These can be seen by pressing 'j' and 'k' to single-step +forward and backward through events. Note that these SVG diagrams are +created from an intermediate SARIF directed graph representation generated from +@code{program_state} objects. The SARIF representation can be easier to +read - for example, rather than storing the contents of memory via byte +offsets, it uses fields for structs and element indexes for arrays, +recursively. However it is a different representation, and thus bugs could +be hidden by this transformation. Generating the SVG diagrams requires +an invocation of "dot" per event, so it noticeably slows down diagnostic +emission, hence the opt-in command-line flag. The SARIF and ``dot'' +representations can be seen by @code{__analyzer_dump_xml} and +@code{__analyzer_dump_dot} below (writing them to stderr), or by adding +@code{show-state-diagrams-sarif=yes} and +@code{show-state-diagrams-dot-src=yes} to the html sink, which shows +them within the generated HTML next to the generated SVG. + @end itemize Assuming that you have the @@ -688,6 +707,15 @@ extern void __analyzer_dump_capacity (const void *ptr); will emit a warning describing the capacity of the base region of the region pointed to by the 1st argument. +@item __analyzer_dump_dot +@smallexample +__analyzer_dump_dot (); +@end smallexample + +will dump GraphViz .dot source to stderr reaches the call in its +traversal of the source. This .dot source implements a diagram +describing the analyzer’s state. + @item __analyzer_dump_escaped @smallexample extern void __analyzer_dump_escaped (void); @@ -764,6 +792,14 @@ will emit a warning describing the state of the 2nd argument a name matching the 1st argument (which must be a string literal). This is for use when debugging, and may be of use in DejaGnu tests. +@item __analyzer_dump_sarif +@smallexample +__analyzer_dump_sarif (); +@end smallexample + +will dump the copious information about the analyzer's state each time it +reaches the call in its traversal of the source. + @item __analyzer_eval @smallexample __analyzer_eval (expr); diff --git a/gcc/doc/avr-mmcu.texi b/gcc/doc/avr-mmcu.texi index feb7725..5efcc81 100644 --- a/gcc/doc/avr-mmcu.texi +++ b/gcc/doc/avr-mmcu.texi @@ -50,15 +50,15 @@ @item @anchor{avrxmega2}avrxmega2 ``XMEGA'' devices with more than 8@tie{}KiB and up to 64@tie{}KiB of program memory. -@*@var{mcu}@tie{}= @code{atxmega8e5}, @code{atxmega16a4}, @code{atxmega16a4u}, @code{atxmega16c4}, @code{atxmega16d4}, @code{atxmega16e5}, @code{atxmega32a4}, @code{atxmega32a4u}, @code{atxmega32c3}, @code{atxmega32c4}, @code{atxmega32d3}, @code{atxmega32d4}, @code{atxmega32e5}, @code{avr64da28}, @code{avr64da32}, @code{avr64da48}, @code{avr64da64}, @code{avr64db28}, @code{avr64db32}, @code{avr64db48}, @code{avr64db64}, @code{avr64dd14}, @code{avr64dd20}, @code{avr64dd28}, @code{avr64dd32}, @code{avr64du28}, @code{avr64du32}, @code{avr64ea28}, @code{avr64ea32}, @code{avr64ea48}, @code{avr64sd28}, @code{avr64sd32}, @code{avr64sd48}. +@*@var{mcu}@tie{}= @code{atxmega8e5}, @code{atxmega16a4}, @code{atxmega16a4u}, @code{atxmega16c4}, @code{atxmega16d4}, @code{atxmega16e5}, @code{atxmega32a4}, @code{atxmega32a4u}, @code{atxmega32c3}, @code{atxmega32c4}, @code{atxmega32d3}, @code{atxmega32d4}, @code{atxmega32e5}, @code{avr64da28}, @code{avr64da28s}, @code{avr64da32}, @code{avr64da32s}, @code{avr64da48}, @code{avr64da48s}, @code{avr64da64}, @code{avr64da64s}, @code{avr64db28}, @code{avr64db32}, @code{avr64db48}, @code{avr64db64}, @code{avr64dd14}, @code{avr64dd20}, @code{avr64dd28}, @code{avr64dd32}, @code{avr64du28}, @code{avr64du32}, @code{avr64ea28}, @code{avr64ea32}, @code{avr64ea48}, @code{avr64sd28}, @code{avr64sd32}, @code{avr64sd48}. @item @anchor{avrxmega3}avrxmega3 ``XMEGA'' devices with up to 64@tie{}KiB of combined program memory and RAM, and with program memory visible in the RAM address space. -@*@var{mcu}@tie{}= @code{attiny202}, @code{attiny204}, @code{attiny212}, @code{attiny214}, @code{attiny402}, @code{attiny404}, @code{attiny406}, @code{attiny412}, @code{attiny414}, @code{attiny416}, @code{attiny416auto}, @code{attiny417}, @code{attiny424}, @code{attiny426}, @code{attiny427}, @code{attiny804}, @code{attiny806}, @code{attiny807}, @code{attiny814}, @code{attiny816}, @code{attiny817}, @code{attiny824}, @code{attiny826}, @code{attiny827}, @code{attiny1604}, @code{attiny1606}, @code{attiny1607}, @code{attiny1614}, @code{attiny1616}, @code{attiny1617}, @code{attiny1624}, @code{attiny1626}, @code{attiny1627}, @code{attiny3214}, @code{attiny3216}, @code{attiny3217}, @code{attiny3224}, @code{attiny3226}, @code{attiny3227}, @code{atmega808}, @code{atmega809}, @code{atmega1608}, @code{atmega1609}, @code{atmega3208}, @code{atmega3209}, @code{atmega4808}, @code{atmega4809}, @code{avr16dd14}, @code{avr16dd20}, @code{avr16dd28}, @code{avr16dd32}, @code{avr16du14}, @code{avr16du20}, @code{avr16du28}, @code{avr16du32}, @code{avr16ea28}, @code{avr16ea32}, @code{avr16ea48}, @code{avr16eb14}, @code{avr16eb20}, @code{avr16eb28}, @code{avr16eb32}, @code{avr32da28}, @code{avr32da32}, @code{avr32da48}, @code{avr32db28}, @code{avr32db32}, @code{avr32db48}, @code{avr32dd14}, @code{avr32dd20}, @code{avr32dd28}, @code{avr32dd32}, @code{avr32du14}, @code{avr32du20}, @code{avr32du28}, @code{avr32du32}, @code{avr32ea28}, @code{avr32ea32}, @code{avr32ea48}, @code{avr32sd20}, @code{avr32sd28}, @code{avr32sd32}. +@*@var{mcu}@tie{}= @code{attiny202}, @code{attiny204}, @code{attiny212}, @code{attiny214}, @code{attiny402}, @code{attiny404}, @code{attiny406}, @code{attiny412}, @code{attiny414}, @code{attiny416}, @code{attiny416auto}, @code{attiny417}, @code{attiny424}, @code{attiny426}, @code{attiny427}, @code{attiny804}, @code{attiny806}, @code{attiny807}, @code{attiny814}, @code{attiny816}, @code{attiny817}, @code{attiny824}, @code{attiny826}, @code{attiny827}, @code{attiny1604}, @code{attiny1606}, @code{attiny1607}, @code{attiny1614}, @code{attiny1616}, @code{attiny1617}, @code{attiny1624}, @code{attiny1626}, @code{attiny1627}, @code{attiny3214}, @code{attiny3216}, @code{attiny3217}, @code{attiny3224}, @code{attiny3226}, @code{attiny3227}, @code{atmega808}, @code{atmega809}, @code{atmega1608}, @code{atmega1609}, @code{atmega3208}, @code{atmega3209}, @code{atmega4808}, @code{atmega4809}, @code{avr16dd14}, @code{avr16dd20}, @code{avr16dd28}, @code{avr16dd32}, @code{avr16du14}, @code{avr16du20}, @code{avr16du28}, @code{avr16du32}, @code{avr16ea28}, @code{avr16ea32}, @code{avr16ea48}, @code{avr16eb14}, @code{avr16eb20}, @code{avr16eb28}, @code{avr16eb32}, @code{avr32da28}, @code{avr32da28s}, @code{avr32da32}, @code{avr32da32s}, @code{avr32da48}, @code{avr32da48s}, @code{avr32db28}, @code{avr32db32}, @code{avr32db48}, @code{avr32dd14}, @code{avr32dd20}, @code{avr32dd28}, @code{avr32dd32}, @code{avr32du14}, @code{avr32du20}, @code{avr32du28}, @code{avr32du32}, @code{avr32ea28}, @code{avr32ea32}, @code{avr32ea48}, @code{avr32sd20}, @code{avr32sd28}, @code{avr32sd32}. @item @anchor{avrxmega4}avrxmega4 ``XMEGA'' devices with more than 64@tie{}KiB and up to 128@tie{}KiB of program memory. -@*@var{mcu}@tie{}= @code{atxmega64a3}, @code{atxmega64a3u}, @code{atxmega64a4u}, @code{atxmega64b1}, @code{atxmega64b3}, @code{atxmega64c3}, @code{atxmega64d3}, @code{atxmega64d4}, @code{avr128da28}, @code{avr128da32}, @code{avr128da48}, @code{avr128da64}, @code{avr128db28}, @code{avr128db32}, @code{avr128db48}, @code{avr128db64}. +@*@var{mcu}@tie{}= @code{atxmega64a3}, @code{atxmega64a3u}, @code{atxmega64a4u}, @code{atxmega64b1}, @code{atxmega64b3}, @code{atxmega64c3}, @code{atxmega64d3}, @code{atxmega64d4}, @code{avr128da28}, @code{avr128da28s}, @code{avr128da32}, @code{avr128da32s}, @code{avr128da48}, @code{avr128da48s}, @code{avr128da64}, @code{avr128da64s}, @code{avr128db28}, @code{avr128db32}, @code{avr128db48}, @code{avr128db64}. @item @anchor{avrxmega5}avrxmega5 ``XMEGA'' devices with more than 64@tie{}KiB and up to 128@tie{}KiB of program memory and more than 64@tie{}KiB of RAM. diff --git a/gcc/doc/cfg.texi b/gcc/doc/cfg.texi index b8c6427..bbd6694 100644 --- a/gcc/doc/cfg.texi +++ b/gcc/doc/cfg.texi @@ -297,10 +297,12 @@ edge. The opposite conversion is difficult, but should not happen anyway. The edges can be eliminated via @code{purge_dead_edges} call. @findex REG_EH_REGION, EDGE_ABNORMAL_CALL -In the RTL representation, the destination of an exception edge is -specified by @code{REG_EH_REGION} note attached to the insn. -In case of a trapping call the @code{EDGE_ABNORMAL_CALL} flag is set -too. In the @code{GIMPLE} representation, this extra flag is not set. +In the RTL representation, a @code{REG_EH_REGION} note is attached to +an instruction that can throw an exception. The destination of the +exception edge originating at such an instruction is specified by the +value of the @code{REG_EH_REGION} note. In case of a trapping call +the @code{EDGE_ABNORMAL_CALL} flag is set too. In the @code{GIMPLE} +representation, this extra flag is not set. @findex may_trap_p, tree_could_trap_p In the RTL representation, the predicate @code{may_trap_p} may be used diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi index ed766e5..8c29e24 100644 --- a/gcc/doc/extend.texi +++ b/gcc/doc/extend.texi @@ -26,39 +26,17 @@ 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. * OpenACC:: Extensions for offloading code to accelerator devices. +* _Countof:: The number of elements of arrays. * Inline:: Defining inline functions (as fast as macros). * Volatiles:: What constitutes an access to a volatile object. * 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 +1574,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 +1712,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 +1729,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 +1758,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 +1798,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 +1815,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 @@ -1918,6 +1934,13 @@ Note that if such a function is called indirectly the compiler may or may not inline it depending on optimization level and a failure to inline an indirect call may or may not be diagnosed. +If you need to use the inlined function in multiple translation units, +you should put the @code{always_inline} attribute on a function +definition in a header file that is included in all translation units +where the function is used. Link-time optimization can inline +functions across translation units, but only if an optimization level +that normally enables inlining is additionally specified. + @cindex @code{artificial} function attribute @item artificial This attribute is useful for small inline wrappers that if possible @@ -2023,24 +2046,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 +2250,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 +2321,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 +2376,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 @@ -2835,13 +2887,18 @@ my_memcpy (void *dest, const void *src, size_t len) @cindex @code{nonnull_if_nonzero} function attribute @item nonnull_if_nonzero @itemx nonnull_if_nonzero (@var{arg-index}, @var{arg2-index}) +@itemx nonnull_if_nonzero (@var{arg-index}, @var{arg2-index}, @var{arg3-index}) The @code{nonnull_if_nonzero} attribute is a conditional version of the -@code{nonnull} attribute. It has two arguments, the first argument +@code{nonnull} attribute. It has two or three arguments, the first argument shall be argument index of a pointer argument which must be in some cases non-null and the second argument shall be argument index of an integral argument (other than boolean). If the integral argument is zero, the pointer argument can be null, if it is non-zero, the pointer -argument must not be null. +argument must not be null. If three arguments are provided, the third +argument shall be argument index of another integral argument (other than +boolean) and the pointer argument can be null if either of the integral +arguments are zero and if both are non-zero, the pointer argument must not +be null. @smallexample extern void * @@ -2851,12 +2908,21 @@ extern void * my_memcpy2 (void *dest, const void *src, size_t len) __attribute__((nonnull_if_nonzero (1, 3), nonnull_if_nonzero (2, 3))); +extern size_t +my_fread (void *buf, size_t size, size_t count, FILE *stream) + __attribute__((nonnull (4), + nonnull_if_nonzero (1, 2, 3))); @end smallexample With these declarations, it is invalid to call @code{my_memcpy (NULL, NULL, 0);} or to -call @code{my_memcpy2 (NULL, NULL, 4);} but it is valid -to call @code{my_memcpy2 (NULL, NULL, 0);}. This attribute should be +call @code{my_memcpy2 (NULL, NULL, 4);} or to call +@code{my_fread(@var{buf}, 0, 0, NULL);} or to call +@code{my_fread(NULL, 1, 1, @var{stream});} but it is valid +to call @code{my_memcpy2 (NULL, NULL, 0);} or +@code{my_fread(NULL, 0, 0, @var{stream});} or +@code{my_fread(NULL, 0, 1, @var{stream});} or +@code{my_fread(NULL, 1, 0, @var{stream});}. This attribute should be used on declarations which have e.g.@: an exception for zero sizes, in which case null may be passed. @@ -3740,7 +3806,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 @@ -3827,10 +3893,21 @@ behavior and permissible arguments are the same as for the command-line option @cindex @code{outline-atomics} function attribute, AArch64 @item outline-atomics +@itemx no-outline-atomics Enable or disable calls to out-of-line helpers to implement atomic operations. This corresponds to the behavior of the command-line options @option{-moutline-atomics} and @option{-mno-outline-atomics}. +@cindex @code{max-vectorization} function attribute, AArch64 +@item max-vectorization +@itemx no-max-vectorization +@code{max-vectorization} tells GCC's vectorizer to treat all vector +loops as being more profitable than the original scalar loops when +optimizing the current function. @code{no-max-vectorization} disables +this behavior. +This corresponds to the behavior of the command-line options +@option{-mmax-vectorization} and @option{-mno-max-vectorization}. + @cindex @code{indirect_return} function attribute, AArch64 @item indirect_return The @code{indirect_return} attribute can be applied to a function type @@ -3887,7 +3964,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 +3990,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 +4080,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 +4158,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 +4310,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 +4482,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 +4560,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 +4589,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 +4621,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 +4694,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 +4724,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 +4753,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 +4827,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 +4890,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 +4926,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 +4950,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 +4968,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 +5007,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 +5105,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 +5255,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 +5346,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 +5415,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 +5431,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 +5628,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 +5731,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 +5762,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 +5823,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 +5888,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 +5970,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 +5992,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 +6006,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: @@ -6061,10 +6138,18 @@ pass arguments, unless it takes a variable number of arguments. @cindex @code{no_callee_saved_registers} function attribute, x86 @item no_callee_saved_registers Use this attribute to indicate that the specified function has no -callee-saved registers. That is, all registers can be used as scratch -registers. For example, this attribute can be used for a function -called from the interrupt handler assembly stub which will preserve -all registers and return from interrupt. +callee-saved registers. That is, all registers, except for stack and +frame pointers, can be used as scratch registers. For example, this +attribute can be used for a function called from the interrupt handler +assembly stub which will preserve all registers and return from +interrupt. + +@cindex @code{preserve_none} function attribute, x86 +@item preserve_none +This attribute is similar to @code{no_callee_saved_registers}, except +on x86-64, r12, r13, r14, r15, rdi and rsi registers are used for +integer parameter passing and this calling convention is subject to +change. @cindex @code{no_caller_saved_registers} function attribute, x86 @item no_caller_saved_registers @@ -6073,9 +6158,10 @@ caller-saved registers. That is, all registers are callee-saved. For example, this attribute can be used for a function called from an interrupt handler. The compiler generates proper function entry and exit sequences to save and restore any modified registers, except for -the EFLAGS register. Since GCC doesn't preserve SSE, MMX nor x87 -states, the GCC option @option{-mgeneral-regs-only} should be used to -compile functions with @code{no_caller_saved_registers} attribute. +the EFLAGS register. Since GCC doesn't preserve YMM nor ZMM registers, +@code{no_caller_saved_registers} attribute can't be used on functions +with AVX enabled. Note that MMX and x87 registers aren't preserved by +@code{no_caller_saved_registers} attribute. @cindex @code{interrupt} function attribute, x86 @item interrupt @@ -6633,23 +6719,10 @@ Enable/disable the generation of the USER_MSR instructions. Enable/disable the generation of the APX features, including EGPR, PUSH2POP2, NDD and PPX. -@cindex @code{target("avx10.1-256")} function attribute, x86 -@item avx10.1-256 -@itemx no-avx10.1-256 -Enable the generation of the AVX10.1 instructions with 256 bit support. -Disable the generation of the AVX10.1 instructions. - @cindex @code{target("avx10.1")} function attribute, x86 @item avx10.1 @itemx no-avx10.1 -Enable the generation of the AVX10.1 instructions with 512 bit support. -Disable the generation of the AVX10.1 instructions. - -@cindex @code{target("avx10.1-512")} function attribute, x86 -@item avx10.1-512 -@itemx no-avx10.1-512 -Enable the generation of the AVX10.1 instructions with 512 bit support. -Disable the generation of the AVX10.1 instructions. +Enable/Disable the generation of the AVX10.1 instructions. @cindex @code{target("avx10.2")} function attribute, x86 @item avx10.2 @@ -6879,7 +6952,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 +6967,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 +6981,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 +7023,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. @@ -7285,7 +7358,7 @@ truncate the copy without appending the terminating @code{NUL} character. Using the attribute makes it possible to suppress the warning. However, when the array is declared with the attribute the call to @code{strlen} is diagnosed because when the array doesn't contain a @code{NUL}-terminated -string the call is undefined. To copy, compare, of search non-string +string the call is undefined. To copy, compare, or search non-string character arrays use the @code{memcpy}, @code{memcmp}, @code{memchr}, and other functions that operate on arrays of bytes. In addition, calling @code{strnlen} and @code{strndup} with such arrays is safe @@ -7600,7 +7673,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 +7685,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 +7850,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 +7875,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 +7904,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 +7923,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 +7939,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 +7960,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 +8025,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 +8055,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 +8069,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 +8084,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 +8092,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 +8115,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 +8143,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 +8161,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 +8203,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 +9072,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 +9082,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 +9108,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 +9119,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 +9146,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 +9175,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 @@ -9137,7 +9210,7 @@ NoError: @item unused This feature is intended for program-generated code that may contain unused labels, but which is compiled with @option{-Wall}. It is -not normally appropriate to use in it human-written code, though it +not normally appropriate to use it in human-written code, though it could be useful in cases where the code that jumps to the label is contained within an @code{#ifdef} conditional. @@ -9158,7 +9231,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 +9276,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 +9343,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 +9353,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 +10004,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 @@ -10247,6 +10415,11 @@ loop or a @code{#pragma GCC ivdep}, and applies only to the loop that follows. @var{n} is an integer constant expression specifying the unrolling factor. The values of @math{0} and @math{1} block any unrolling of the loop. +If the loop was vectorized the unroll factor specified will be used to seed the +vectorizer unroll factor. Whether the loop is unrolled or not will be +determined by target costing. The resulting vectorized loop may still be +unrolled more in later passes depending on the target costing. + @end table @node Thread-Local @@ -10533,7 +10706,7 @@ and @samp{[[omp::sequence(...)]]} in C and C++, GCC needs to be invoked with the @option{-fopenmp} option. This option also arranges for automatic linking of the OpenMP runtime library. -@xref{,,,libgomp,GNU Offloading and Multi Processing Runtime Library}. +@xref{Top,,,libgomp,GNU Offloading and Multi Processing Runtime Library}. @xref{OpenMP and OpenACC Options}, for additional options useful with @option{-fopenmp}. @@ -10555,11 +10728,41 @@ To enable the processing of OpenACC directives @samp{#pragma acc} in C and C++, GCC needs to be invoked with the @option{-fopenacc} option. This option also arranges for automatic linking of the OpenACC runtime library. -@xref{,,,libgomp,GNU Offloading and Multi Processing Runtime Library}. +@xref{Top,,,libgomp,GNU Offloading and Multi Processing Runtime Library}. @xref{OpenMP and OpenACC Options}, for additional options useful with @option{-fopenacc}. +@node _Countof +@section Determining the Number of Elements of Arrays +@cindex _Countof +@cindex number of elements + +The keyword @code{_Countof} determines +the number of elements of an array operand. +Its syntax is similar to @code{sizeof}. +The operand must be +a parenthesized complete array type name +or an expression of such a type. +For example: + +@smallexample +int a[n]; +_Countof (a); // returns n +_Countof (int [7][3]); // returns 7 +@end smallexample + +The result of this operator is an integer constant expression, +unless the array has a variable number of elements. +The operand is only evaluated +if the array has a variable number of elements. +For example: + +@smallexample +_Countof (int [7][n++]); // integer constant expression +_Countof (int [n++][7]); // run-time value; n++ is evaluated +@end smallexample + @node Inline @section An Inline Function is As Fast As a Macro @cindex inline functions @@ -12160,15 +12363,6 @@ for the @samp{att} and @samp{intel} dialects of assembler: @item @code{%3} @tab @code{$.L3} @tab @code{OFFSET FLAT:.L3} -@item @code{%4} -@tab @code{$8} -@tab @code{8} -@item @code{%5} -@tab @code{%xmm0} -@tab @code{xmm0} -@item @code{%7} -@tab @code{$0} -@tab @code{0} @end multitable The table below shows the list of supported modifiers and their effects. @@ -12185,32 +12379,17 @@ The table below shows the list of supported modifiers and their effects. @tab @code{%b0} @tab @code{%al} @tab @code{al} -@item @code{B} -@tab print the opcode suffix of b. -@tab @code{%B0} -@tab @code{b} -@tab @item @code{c} @tab Require a constant operand and print the constant expression with no punctuation. @tab @code{%c1} @tab @code{2} @tab @code{2} -@item @code{d} -@tab print duplicated register operand for AVX instruction. -@tab @code{%d5} -@tab @code{%xmm0, %xmm0} -@tab @code{xmm0, xmm0} @item @code{E} @tab Print the address in Double Integer (DImode) mode (8 bytes) when the target is 64-bit. Otherwise mode is unspecified (VOIDmode). @tab @code{%E1} @tab @code{%(rax)} @tab @code{[rax]} -@item @code{g} -@tab Print the V16SFmode name of the register. -@tab @code{%g0} -@tab @code{%zmm0} -@tab @code{zmm0} @item @code{h} @tab Print the QImode name for a ``high'' register. @tab @code{%h0} @@ -12232,16 +12411,6 @@ high 8 bytes of SSE values. For a memref in (%rax), it generates @tab @code{%l3} @tab @code{.L3} @tab @code{.L3} -@item @code{L} -@tab print the opcode suffix of l. -@tab @code{%L0} -@tab @code{l} -@tab -@item @code{N} -@tab print maskz. -@tab @code{%N7} -@tab @code{@{z@}} -@tab @code{@{z@}} @item @code{p} @tab Print raw symbol name (without syntax-specific prefixes). @tab @code{%p2} @@ -12257,76 +12426,20 @@ issue the bare constant. See @code{p} above. @tab @code{%q0} @tab @code{%rax} @tab @code{rax} -@item @code{Q} -@tab print the opcode suffix of q. -@tab @code{%Q0} -@tab @code{q} -@tab -@item @code{R} -@tab print embedded rounding and sae. -@tab @code{%R4} -@tab @code{@{rn-sae@}, } -@tab @code{, @{rn-sae@}} -@item @code{r} -@tab print only sae. -@tab @code{%r4} -@tab @code{@{sae@}, } -@tab @code{, @{sae@}} -@item @code{s} -@tab print a shift double count, followed by the assemblers argument -delimiterprint the opcode suffix of s. -@tab @code{%s1} -@tab @code{$2, } -@tab @code{2, } -@item @code{S} -@tab print the opcode suffix of s. -@tab @code{%S0} -@tab @code{s} -@tab -@item @code{t} -@tab print the V8SFmode name of the register. -@tab @code{%t5} -@tab @code{%ymm0} -@tab @code{ymm0} -@item @code{T} -@tab print the opcode suffix of t. -@tab @code{%T0} -@tab @code{t} -@tab -@item @code{V} -@tab print naked full integer register name without %. -@tab @code{%V0} -@tab @code{eax} -@tab @code{eax} @item @code{w} @tab Print the HImode name of the register. @tab @code{%w0} @tab @code{%ax} @tab @code{ax} -@item @code{W} -@tab print the opcode suffix of w. -@tab @code{%W0} -@tab @code{w} -@tab -@item @code{x} -@tab print the V4SFmode name of the register. -@tab @code{%x5} -@tab @code{%xmm0} -@tab @code{xmm0} -@item @code{y} -@tab print "st(0)" instead of "st" as a register. -@tab @code{%y6} -@tab @code{%st(0)} -@tab @code{st(0)} @item @code{z} @tab Print the opcode suffix for the size of the current integer operand (one of @code{b}/@code{w}/@code{l}/@code{q}). @tab @code{%z0} @tab @code{l} @tab -@item @code{Z} -@tab Like @code{z}, with special suffixes for x87 instructions. @end multitable +@code{V} is a special modifier which prints the name of the full integer +register without @code{%}. @anchor{x86floatingpointasmoperands} @subsubsection x86 Floating-Point @code{asm} Operands @@ -12529,6 +12642,7 @@ The list below describes the supported modifiers and their effects for RISC-V. @item @code{z} @tab Print ''@code{zero}'' instead of 0 if the operand is an immediate with a value of zero. @item @code{i} @tab Print the character ''@code{i}'' if the operand is an immediate. @item @code{N} @tab Print the register encoding as integer (0 - 31). +@item @code{H} @tab Print the name of the next register for integer. @end multitable @anchor{shOperandmodifiers} @@ -12910,7 +13024,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. @@ -12921,6 +13036,7 @@ C and/or C++ standards, while others remain specific to GNU C. * Binary constants:: Binary constants using the @samp{0b} prefix. * Dollar Signs:: Dollar sign is allowed in identifiers. * Character Escapes:: @samp{\e} stands for the character @key{ESC}. +* Raw String Literals:: C++ raw string literals are supported in C. * Alternate Keywords:: @code{__const__}, @code{__asm__}, etc., for header files. * Function Names:: Printable strings which are the name of the current function. @@ -13610,22 +13726,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 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. +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. + +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++. + +@node Boolean Type +@subsection Support for the @code{_Bool} Type +@cindex boolean type +@cindex @code{_Bool} keyword -This extension is not supported by GNU C++. +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. @@ -13887,6 +14058,25 @@ machines, typically because the target assembler does not allow them. You can use the sequence @samp{\e} in a string or character constant to stand for the ASCII character @key{ESC}. +@node Raw String Literals +@subsection Raw String Literals +@cindex raw string literals +@cindex string literals, raw + +The C++11 standard added syntax for raw string literals prefixed +with @samp{R}. This syntax allows you to use an arbitrary delimiter +sequence instead of escaping special characters within the string. +For example, these string constants are all equivalent: + +@smallexample +const char *s1 = "\\"; +const char *s2 = R"(\)"; +const char *s3 = R"foo(\)foo"; +@end smallexample + +As an extension, GCC also accepts raw string literals in C with +@option{-std=gnu99} or later. + @node Alternate Keywords @subsection Alternate Keywords @cindex alternate keywords @@ -14169,6 +14359,1527 @@ 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 acospi +@findex acospif +@findex acospil +@findex alloca +@findex asin +@findex asinf +@findex asinh +@findex asinhf +@findex asinhl +@findex asinl +@findex asinpi +@findex asinpif +@findex asinpil +@findex atan +@findex atan2 +@findex atan2f +@findex atan2l +@findex atan2pi +@findex atan2pif +@findex atan2pil +@findex atanf +@findex atanh +@findex atanhf +@findex atanhl +@findex atanl +@findex atanpi +@findex atanpif +@findex atanpil +@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 cospi +@findex cospif +@findex cospil +@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 sinpi +@findex sinpif +@findex sinpil +@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 tanpi +@findex tanpif +@findex tanpil +@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{acospi}, @code{acospif}, @code{acospil}, +@code{asinpi}, @code{asinpif}, @code{asinpil}, @code{atan2pi}, @code{atan2pif}, +@code{atan2pil}, @code{atanpi}, @code{atanpif}, @code{atanpil}, @code{bcmp}, +@code{bzero}, @code{cospi}, @code{cospif}, @code{cospil}, +@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{sinpif}, @code{sinpil}, @code{sinpi}, +@code{stpcpy}, @code{stpncpy}, @code{strcasecmp}, @code{strdup}, +@code{strfmon}, @code{strncasecmp}, @code{strndup}, @code{strnlen}, +@code{tanpif}, @code{tanpil}, @code{tanpi}, @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. @var{poly} is required to be a compile-time constant. +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. @var{poly} is required to be a compile-time constant. +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 +16052,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 +16506,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 - -The following built-in functions -are intended to be compatible with those described -in the @cite{Intel Itanium Processor-specific Application Binary Interface}, -section 7.4. As such, they depart from normal GCC practice by not using -the @samp{__builtin_} prefix and also by being overloaded so that they -work on multiple types. - -The definition given in the Intel documentation allows only for the use of -the types @code{int}, @code{long}, @code{long long} or their unsigned -counterparts. GCC allows any scalar type that is 1, 2, 4 or 8 bytes in -size other than the C type @code{_Bool} or the C++ type @code{bool}. -Operations on pointer arguments are performed as if the operands were -of the @code{uintptr_t} type. That is, they are not scaled by the size -of the type to which the pointer points. - -These functions are implemented in terms of the @samp{__atomic} -builtins (@pxref{__atomic Builtins}). They should not be used for new -code which should use the @samp{__atomic} builtins instead. - -Not all operations are supported by all target processors. If a particular -operation cannot be implemented on the target processor, a call to an -external function is generated. The external function carries the same name -as the built-in version, with an additional suffix -@samp{_@var{n}} where @var{n} is the size of the data type. - -In most cases, these built-in functions are considered a @dfn{full barrier}. -That is, -no memory operand is moved across the operation, either forward or -backward. Further, instructions are issued as necessary to prevent the -processor from speculating loads across the operation and from queuing stores -after the operation. - -All of the routines are described in the Intel documentation to take -``an optional list of variables protected by the memory barrier''. It's -not clear what is meant by that; it could mean that @emph{only} the -listed variables are protected, or it could mean a list of additional -variables to be protected. The list is ignored by GCC which treats it as -empty. GCC interprets an empty list as meaning that all globally -accessible variables should be protected. - -@defbuiltin{@var{type} __sync_fetch_and_add (@var{type} *@var{ptr}, @var{type} @var{value}, ...)} -@defbuiltinx{@var{type} __sync_fetch_and_sub (@var{type} *@var{ptr}, @var{type} @var{value}, ...)} -@defbuiltinx{@var{type} __sync_fetch_and_or (@var{type} *@var{ptr}, @var{type} @var{value}, ...)} -@defbuiltinx{@var{type} __sync_fetch_and_and (@var{type} *@var{ptr}, @var{type} @var{value}, ...)} -@defbuiltinx{@var{type} __sync_fetch_and_xor (@var{type} *@var{ptr}, @var{type} @var{value}, ...)} -@defbuiltinx{@var{type} __sync_fetch_and_nand (@var{type} *@var{ptr}, @var{type} @var{value}, ...)} -These built-in functions perform the operation suggested by the name, and -returns the value that had previously been in memory. That is, operations -on integer operands have the following semantics. Operations on pointer -arguments are performed as if the operands were of the @code{uintptr_t} -type. That is, they are not scaled by the size of the type to which -the pointer points. - -@smallexample -@{ tmp = *ptr; *ptr @var{op}= value; return tmp; @} -@{ tmp = *ptr; *ptr = ~(tmp & value); return tmp; @} // nand -@end smallexample - -The object pointed to by the first argument must be of integer or pointer -type. It must not be a boolean type. - -@emph{Note:} GCC 4.4 and later implement @code{__sync_fetch_and_nand} -as @code{*ptr = ~(tmp & value)} instead of @code{*ptr = ~tmp & value}. -@enddefbuiltin - -@defbuiltin{@var{type} __sync_add_and_fetch (@var{type} *@var{ptr}, @ - @var{type} @var{value}, ...)} -@defbuiltinx{@var{type} __sync_sub_and_fetch (@var{type} *@var{ptr}, @var{type} @var{value}, ...)} -@defbuiltinx{@var{type} __sync_or_and_fetch (@var{type} *@var{ptr}, @var{type} @var{value}, ...)} -@defbuiltinx{@var{type} __sync_and_and_fetch (@var{type} *@var{ptr}, @var{type} @var{value}, ...)} -@defbuiltinx{@var{type} __sync_xor_and_fetch (@var{type} *@var{ptr}, @var{type} @var{value}, ...)} -@defbuiltinx{@var{type} __sync_nand_and_fetch (@var{type} *@var{ptr}, @var{type} @var{value}, ...)} -These built-in functions perform the operation suggested by the name, and -return the new value. That is, operations on integer operands have -the following semantics. Operations on pointer operands are performed as -if the operand's type were @code{uintptr_t}. - -@smallexample -@{ *ptr @var{op}= value; return *ptr; @} -@{ *ptr = ~(*ptr & value); return *ptr; @} // nand -@end smallexample - -The same constraints on arguments apply as for the corresponding -@code{__sync_op_and_fetch} built-in functions. - -@emph{Note:} GCC 4.4 and later implement @code{__sync_nand_and_fetch} -as @code{*ptr = ~(*ptr & value)} instead of -@code{*ptr = ~*ptr & value}. -@enddefbuiltin - -@defbuiltin{bool __sync_bool_compare_and_swap (@var{type} *@var{ptr}, @var{type} @var{oldval}, @var{type} @var{newval}, ...)} -@defbuiltinx{@var{type} __sync_val_compare_and_swap (@var{type} *@var{ptr}, @var{type} @var{oldval}, @var{type} @var{newval}, ...)} -These built-in functions perform an atomic compare and swap. -That is, if the current -value of @code{*@var{ptr}} is @var{oldval}, then write @var{newval} into -@code{*@var{ptr}}. - -The ``bool'' version returns @code{true} if the comparison is successful and -@var{newval} is written. The ``val'' version returns the contents -of @code{*@var{ptr}} before the operation. -@enddefbuiltin - -@defbuiltin{void __sync_synchronize (...)} -This built-in function issues a full memory barrier. -@enddefbuiltin - -@defbuiltin{@var{type} __sync_lock_test_and_set (@var{type} *@var{ptr}, @var{type} @var{value}, ...)} -This built-in function, as described by Intel, is not a traditional test-and-set -operation, but rather an atomic exchange operation. It writes @var{value} -into @code{*@var{ptr}}, and returns the previous contents of -@code{*@var{ptr}}. +@node Atomic Memory Access +@section Builtins for Atomic Memory Access +@cindex atomic memory access builtins +@cindex builtins for atomic memory access -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. +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. -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 +16630,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 +16860,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 +17030,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 +17069,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 +17167,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 +17194,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 +17399,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 +17931,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 +17955,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 +17974,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 @@ -17647,7 +17987,6 @@ instructions, but allow the compiler to schedule those calls. * Alpha Built-in Functions:: * ARC Built-in Functions:: * ARC SIMD Built-in Functions:: -* ARM iWMMXt Built-in Functions:: * ARM C Language Extensions (ACLE):: * ARM Floating Point Status and Control Intrinsics:: * ARM ARMv8-M Security Extensions:: @@ -18263,160 +18602,6 @@ _v4hi __builtin_arc_vaddsub4h (__v4hi, __v4hi); _v4hi __builtin_arc_vsubadd4h (__v4hi, __v4hi); @end example -@node ARM iWMMXt Built-in Functions -@subsection ARM iWMMXt Built-in Functions - -These built-in functions are available for the ARM family of -processors when the @option{-mcpu=iwmmxt} switch is used: - -@smallexample -typedef int v2si __attribute__ ((vector_size (8))); -typedef short v4hi __attribute__ ((vector_size (8))); -typedef char v8qi __attribute__ ((vector_size (8))); - -int __builtin_arm_getwcgr0 (void); -void __builtin_arm_setwcgr0 (int); -int __builtin_arm_getwcgr1 (void); -void __builtin_arm_setwcgr1 (int); -int __builtin_arm_getwcgr2 (void); -void __builtin_arm_setwcgr2 (int); -int __builtin_arm_getwcgr3 (void); -void __builtin_arm_setwcgr3 (int); -int __builtin_arm_textrmsb (v8qi, int); -int __builtin_arm_textrmsh (v4hi, int); -int __builtin_arm_textrmsw (v2si, int); -int __builtin_arm_textrmub (v8qi, int); -int __builtin_arm_textrmuh (v4hi, int); -int __builtin_arm_textrmuw (v2si, int); -v8qi __builtin_arm_tinsrb (v8qi, int, int); -v4hi __builtin_arm_tinsrh (v4hi, int, int); -v2si __builtin_arm_tinsrw (v2si, int, int); -long long __builtin_arm_tmia (long long, int, int); -long long __builtin_arm_tmiabb (long long, int, int); -long long __builtin_arm_tmiabt (long long, int, int); -long long __builtin_arm_tmiaph (long long, int, int); -long long __builtin_arm_tmiatb (long long, int, int); -long long __builtin_arm_tmiatt (long long, int, int); -int __builtin_arm_tmovmskb (v8qi); -int __builtin_arm_tmovmskh (v4hi); -int __builtin_arm_tmovmskw (v2si); -long long __builtin_arm_waccb (v8qi); -long long __builtin_arm_wacch (v4hi); -long long __builtin_arm_waccw (v2si); -v8qi __builtin_arm_waddb (v8qi, v8qi); -v8qi __builtin_arm_waddbss (v8qi, v8qi); -v8qi __builtin_arm_waddbus (v8qi, v8qi); -v4hi __builtin_arm_waddh (v4hi, v4hi); -v4hi __builtin_arm_waddhss (v4hi, v4hi); -v4hi __builtin_arm_waddhus (v4hi, v4hi); -v2si __builtin_arm_waddw (v2si, v2si); -v2si __builtin_arm_waddwss (v2si, v2si); -v2si __builtin_arm_waddwus (v2si, v2si); -v8qi __builtin_arm_walign (v8qi, v8qi, int); -long long __builtin_arm_wand(long long, long long); -long long __builtin_arm_wandn (long long, long long); -v8qi __builtin_arm_wavg2b (v8qi, v8qi); -v8qi __builtin_arm_wavg2br (v8qi, v8qi); -v4hi __builtin_arm_wavg2h (v4hi, v4hi); -v4hi __builtin_arm_wavg2hr (v4hi, v4hi); -v8qi __builtin_arm_wcmpeqb (v8qi, v8qi); -v4hi __builtin_arm_wcmpeqh (v4hi, v4hi); -v2si __builtin_arm_wcmpeqw (v2si, v2si); -v8qi __builtin_arm_wcmpgtsb (v8qi, v8qi); -v4hi __builtin_arm_wcmpgtsh (v4hi, v4hi); -v2si __builtin_arm_wcmpgtsw (v2si, v2si); -v8qi __builtin_arm_wcmpgtub (v8qi, v8qi); -v4hi __builtin_arm_wcmpgtuh (v4hi, v4hi); -v2si __builtin_arm_wcmpgtuw (v2si, v2si); -long long __builtin_arm_wmacs (long long, v4hi, v4hi); -long long __builtin_arm_wmacsz (v4hi, v4hi); -long long __builtin_arm_wmacu (long long, v4hi, v4hi); -long long __builtin_arm_wmacuz (v4hi, v4hi); -v4hi __builtin_arm_wmadds (v4hi, v4hi); -v4hi __builtin_arm_wmaddu (v4hi, v4hi); -v8qi __builtin_arm_wmaxsb (v8qi, v8qi); -v4hi __builtin_arm_wmaxsh (v4hi, v4hi); -v2si __builtin_arm_wmaxsw (v2si, v2si); -v8qi __builtin_arm_wmaxub (v8qi, v8qi); -v4hi __builtin_arm_wmaxuh (v4hi, v4hi); -v2si __builtin_arm_wmaxuw (v2si, v2si); -v8qi __builtin_arm_wminsb (v8qi, v8qi); -v4hi __builtin_arm_wminsh (v4hi, v4hi); -v2si __builtin_arm_wminsw (v2si, v2si); -v8qi __builtin_arm_wminub (v8qi, v8qi); -v4hi __builtin_arm_wminuh (v4hi, v4hi); -v2si __builtin_arm_wminuw (v2si, v2si); -v4hi __builtin_arm_wmulsm (v4hi, v4hi); -v4hi __builtin_arm_wmulul (v4hi, v4hi); -v4hi __builtin_arm_wmulum (v4hi, v4hi); -long long __builtin_arm_wor (long long, long long); -v2si __builtin_arm_wpackdss (long long, long long); -v2si __builtin_arm_wpackdus (long long, long long); -v8qi __builtin_arm_wpackhss (v4hi, v4hi); -v8qi __builtin_arm_wpackhus (v4hi, v4hi); -v4hi __builtin_arm_wpackwss (v2si, v2si); -v4hi __builtin_arm_wpackwus (v2si, v2si); -long long __builtin_arm_wrord (long long, long long); -long long __builtin_arm_wrordi (long long, int); -v4hi __builtin_arm_wrorh (v4hi, long long); -v4hi __builtin_arm_wrorhi (v4hi, int); -v2si __builtin_arm_wrorw (v2si, long long); -v2si __builtin_arm_wrorwi (v2si, int); -v2si __builtin_arm_wsadb (v2si, v8qi, v8qi); -v2si __builtin_arm_wsadbz (v8qi, v8qi); -v2si __builtin_arm_wsadh (v2si, v4hi, v4hi); -v2si __builtin_arm_wsadhz (v4hi, v4hi); -v4hi __builtin_arm_wshufh (v4hi, int); -long long __builtin_arm_wslld (long long, long long); -long long __builtin_arm_wslldi (long long, int); -v4hi __builtin_arm_wsllh (v4hi, long long); -v4hi __builtin_arm_wsllhi (v4hi, int); -v2si __builtin_arm_wsllw (v2si, long long); -v2si __builtin_arm_wsllwi (v2si, int); -long long __builtin_arm_wsrad (long long, long long); -long long __builtin_arm_wsradi (long long, int); -v4hi __builtin_arm_wsrah (v4hi, long long); -v4hi __builtin_arm_wsrahi (v4hi, int); -v2si __builtin_arm_wsraw (v2si, long long); -v2si __builtin_arm_wsrawi (v2si, int); -long long __builtin_arm_wsrld (long long, long long); -long long __builtin_arm_wsrldi (long long, int); -v4hi __builtin_arm_wsrlh (v4hi, long long); -v4hi __builtin_arm_wsrlhi (v4hi, int); -v2si __builtin_arm_wsrlw (v2si, long long); -v2si __builtin_arm_wsrlwi (v2si, int); -v8qi __builtin_arm_wsubb (v8qi, v8qi); -v8qi __builtin_arm_wsubbss (v8qi, v8qi); -v8qi __builtin_arm_wsubbus (v8qi, v8qi); -v4hi __builtin_arm_wsubh (v4hi, v4hi); -v4hi __builtin_arm_wsubhss (v4hi, v4hi); -v4hi __builtin_arm_wsubhus (v4hi, v4hi); -v2si __builtin_arm_wsubw (v2si, v2si); -v2si __builtin_arm_wsubwss (v2si, v2si); -v2si __builtin_arm_wsubwus (v2si, v2si); -v4hi __builtin_arm_wunpckehsb (v8qi); -v2si __builtin_arm_wunpckehsh (v4hi); -long long __builtin_arm_wunpckehsw (v2si); -v4hi __builtin_arm_wunpckehub (v8qi); -v2si __builtin_arm_wunpckehuh (v4hi); -long long __builtin_arm_wunpckehuw (v2si); -v4hi __builtin_arm_wunpckelsb (v8qi); -v2si __builtin_arm_wunpckelsh (v4hi); -long long __builtin_arm_wunpckelsw (v2si); -v4hi __builtin_arm_wunpckelub (v8qi); -v2si __builtin_arm_wunpckeluh (v4hi); -long long __builtin_arm_wunpckeluw (v2si); -v8qi __builtin_arm_wunpckihb (v8qi, v8qi); -v4hi __builtin_arm_wunpckihh (v4hi, v4hi); -v2si __builtin_arm_wunpckihw (v2si, v2si); -v8qi __builtin_arm_wunpckilb (v8qi, v8qi); -v4hi __builtin_arm_wunpckilh (v4hi, v4hi); -v2si __builtin_arm_wunpckilw (v2si, v2si); -long long __builtin_arm_wxor (long long, long long); -long long __builtin_arm_wzero (); -@end smallexample - - @node ARM C Language Extensions (ACLE) @subsection ARM C Language Extensions (ACLE) @@ -29555,43 +29740,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 +30268,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 +30286,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/gcov.texi b/gcc/doc/gcov.texi index 8bf87a2..ecf147a 100644 --- a/gcc/doc/gcov.texi +++ b/gcc/doc/gcov.texi @@ -1077,7 +1077,7 @@ condition 1 not covered (true) -: 12:@} @end smallexample -@anchor {gcov prime paths example} +@anchor{gcov prime paths example} When you compile with @option{--coverage -fpath-coverage} and use the option @option{-e} your output looks like this: diff --git a/gcc/doc/gm2.texi b/gcc/doc/gm2.texi index 8baee24..9bd0f0d 100644 --- a/gcc/doc/gm2.texi +++ b/gcc/doc/gm2.texi @@ -540,6 +540,9 @@ lines compiled. @item -fm2-strict-type experimental flag to turn on the new strict type checker. +@item -fm2-strict-type-reason +provides more detail why the types are incompatible. + @item -fm2-whole-program compile all implementation modules and program module at once. Notice that you need to take care if you are compiling different dialect @@ -1495,7 +1498,7 @@ from @samp{bad} will cause an overflow to @samp{foo}. If we compile the code with the following options: @example -$ gm2 -g -fsoft-check-all -O2 -c assignvalue.mod +$ gm2 -g -fsoft-check-all -O2 -fm2-plugin -c assignvalue.mod assignvalue.mod:16:0:inevitable that this error will occur at run time, assignment will result in an overflow @end example @@ -2699,10 +2702,10 @@ PROCEDURE Example (foo, bar: CARDINAL) : CARDINAL ; VAR myout: CARDINAL ; BEGIN - ASM VOLATILE ("movq %1,%%rax; addq %2,%%rax; movq %%rax,%0" + ASM VOLATILE ("movl %1,%%eax; addl %2,%%eax; movl %%eax,%0" : "=rm" (myout) (* outputs *) : "rm" (foo), "rm" (bar) (* inputs *) - : "rax") ; (* we trash *) + : "eax") ; (* we trash *) RETURN( myout ) END Example ; @end example @@ -2720,10 +2723,10 @@ VAR myout: CARDINAL ; BEGIN ASM VOLATILE ( - "movq %[left],%%rax; addq %[right],%%rax; movq %%rax,%[output]" + "movl %[left],%%eax; addl %[right],%%eax; movl %%eax,%[output]" : [output] "=rm" (myout) (* outputs *) : [left] "rm" (foo), [right] "rm" (bar) (* inputs *) - : "rax") ; (* we trash *) + : "eax") ; (* we trash *) RETURN( myout ) END Example ; @end example diff --git a/gcc/doc/implement-c.texi b/gcc/doc/implement-c.texi index a942a12..8f0c2ff 100644 --- a/gcc/doc/implement-c.texi +++ b/gcc/doc/implement-c.texi @@ -10,8 +10,8 @@ A conforming implementation of ISO C is required to document its choice of behavior in each of the areas that are designated ``implementation defined''. The following lists all such areas, along with the section numbers from the ISO/IEC 9899:1990, ISO/IEC -9899:1999 and ISO/IEC 9899:2011 standards. Some areas are only -implementation-defined in one version of the standard. +9899:1999, ISO/IEC 9899:2011 and ISO/IEC 9899:2024 standards. Some +areas are only implementation-defined in one version of the standard. Some choices depend on the externally determined ABI for the platform (including standard character encodings) which GCC follows; these are @@ -30,10 +30,12 @@ a freestanding environment); refer to their documentation for details. * Characters implementation:: * Integers implementation:: * Floating point implementation:: +* Constant expressions implementation:: * Arrays and pointers implementation:: * Hints implementation:: * Structures unions enumerations and bit-fields implementation:: * Qualifiers implementation:: +* Types implementation:: * Declarators implementation:: * Statements implementation:: * Preprocessing directives implementation:: @@ -47,15 +49,15 @@ a freestanding environment); refer to their documentation for details. @itemize @bullet @item -@cite{How a diagnostic is identified (C90 3.7, C99 and C11 3.10, C90, -C99 and C11 5.1.1.3).} +@cite{How a diagnostic is identified (C90 3.7, C99 and C11 3.10, C23 +3.13, C90, C99 and C11 5.1.1.3, C23 5.2.1.3).} Diagnostics consist of all the output sent to stderr by GCC@. @item @cite{Whether each nonempty sequence of white-space characters other than new-line is retained or replaced by one space character in translation -phase 3 (C90, C99 and C11 5.1.1.2).} +phase 3 (C90, C99 and C11 5.1.1.2, C23 5.2.1.2).} @xref{Implementation-defined behavior, , Implementation-defined behavior, cpp, The C Preprocessor}. @@ -72,7 +74,7 @@ of the C library, and are not defined by GCC itself. @item @cite{The mapping between physical source file multibyte characters and the source character set in translation phase 1 (C90, C99 and C11 -5.1.1.2).} +5.1.1.2, C23 5.2.1.2).} @xref{Implementation-defined behavior, , Implementation-defined behavior, cpp, The C Preprocessor}. @@ -85,14 +87,16 @@ behavior, cpp, The C Preprocessor}. @itemize @bullet @item @cite{Which additional multibyte characters may appear in identifiers -and their correspondence to universal character names (C99 and C11 6.4.2).} +and their correspondence to universal character names (C99 and C11 +6.4.2, C23 6.4.3).} @xref{Implementation-defined behavior, , Implementation-defined behavior, cpp, The C Preprocessor}. @item @cite{The number of significant initial characters in an identifier -(C90 6.1.2, C90, C99 and C11 5.2.4.1, C99 and C11 6.4.2).} +(C90 6.1.2, C90, C99 and C11 5.2.4.1, C23 5.3.5.2, C99 and C11 6.4.2, +C23 6.4.3).} For internal names, all characters are significant. For external names, the number of significant characters are defined by the linker; for @@ -102,7 +106,7 @@ almost all targets, all characters are significant. @cite{Whether case distinctions are significant in an identifier with external linkage (C90 6.1.2).} -This is a property of the linker. C99 and C11 require that case distinctions +This is a property of the linker. C99 and later require that case distinctions are always significant in identifiers with external linkage and systems without this property are not supported by GCC@. @@ -113,34 +117,35 @@ systems without this property are not supported by GCC@. @itemize @bullet @item -@cite{The number of bits in a byte (C90 3.4, C99 and C11 3.6).} +@cite{The number of bits in a byte (C90 3.4, C99 and C11 3.6, C23 3.7).} Determined by ABI@. @item @cite{The values of the members of the execution character set (C90, -C99 and C11 5.2.1).} +C99 and C11 5.2.1, C23 5.3.1).} Determined by ABI@. @item @cite{The unique value of the member of the execution character set produced for each of the standard alphabetic escape sequences (C90, C99 and C11 -5.2.2).} +5.2.2, C23 5.3.3).} Determined by ABI@. @item @cite{The value of a @code{char} object into which has been stored any character other than a member of the basic execution character set -(C90 6.1.2.5, C99 and C11 6.2.5).} +(C90 6.1.2.5, C99, C11 and C23 6.2.5).} Determined by ABI@. @item @cite{Which of @code{signed char} or @code{unsigned char} has the same range, representation, and behavior as ``plain'' @code{char} (C90 -6.1.2.5, C90 6.2.1.1, C99 and C11 6.2.5, C99 and C11 6.3.1.1).} +6.1.2.5, C90 6.2.1.1, C99, C11 and C23 6.2.5, C99 and C11 6.3.1.1, C23 +6.3.2.1).} @opindex fsigned-char @opindex funsigned-char @@ -149,16 +154,32 @@ Determined by ABI@. The options @option{-funsigned-char} and Options Controlling C Dialect}. @item +@cite{The literal encoding, which maps of the characters of the +execution character set to the values in a character constant or +string literal (C23 6.2.9, C23 6.4.5.5).} + +Determined by ABI@. + +@item +@cite{The wide literal encoding, of the characters of the execution +character set to the values in a @code{wchar_t} character constant or +@code{wchar_t} string literal (C23 6.2.9, C23 6.4.5.5).} + +Determined by ABI@. + +@item @cite{The mapping of members of the source character set (in character constants and string literals) to members of the execution character -set (C90 6.1.3.4, C99 and C11 6.4.4.4, C90, C99 and C11 5.1.1.2).} +set (C90 6.1.3.4, C99 and C11 6.4.4.4, C23 6.4.5.5, C90, C99 and C11 +5.1.1.2, C23 5.2.1.2).} Determined by ABI@. @item @cite{The value of an integer character constant containing more than one character or containing a character or escape sequence that does not map -to a single-byte execution character (C90 6.1.3.4, C99 and C11 6.4.4.4).} +to a single-byte execution character (C90 6.1.3.4, C99 and C11 +6.4.4.4, C23 6.4.5.5).} @xref{Implementation-defined behavior, , Implementation-defined behavior, cpp, The C Preprocessor}. @@ -169,7 +190,7 @@ multibyte character or a single multibyte character that maps to multiple members of the extended execution character set, or containing a multibyte character or escape sequence not represented in the extended execution character set (C90 6.1.3.4, C99 and C11 -6.4.4.4).} +6.4.4.4, C23 6.4.5.5).} @xref{Implementation-defined behavior, , Implementation-defined behavior, cpp, The C Preprocessor}. @@ -178,7 +199,7 @@ behavior, cpp, The C Preprocessor}. @cite{The current locale used to convert a wide character constant consisting of a single multibyte character that maps to a member of the extended execution character set into a corresponding wide character code (C90 -6.1.3.4, C99 and C11 6.4.4.4).} +6.1.3.4, C99 and C11 6.4.4.4, C23 6.4.5.5).} @xref{Implementation-defined behavior, , Implementation-defined behavior, cpp, The C Preprocessor}. @@ -192,7 +213,7 @@ Such tokens may not be concatenated. @item @cite{The current locale used to convert a wide string literal into -corresponding wide character codes (C90 6.1.4, C99 and C11 6.4.5).} +corresponding wide character codes (C90 6.1.4, C99 and C11 6.4.5, C23 6.4.6).} @xref{Implementation-defined behavior, , Implementation-defined behavior, cpp, The C Preprocessor}. @@ -200,7 +221,7 @@ behavior, cpp, The C Preprocessor}. @item @cite{The value of a string literal containing a multibyte character or escape sequence not represented in the execution character set (C90 6.1.4, -C99 and C11 6.4.5).} +C99 and C11 6.4.5, C23 6.4.6).} @xref{Implementation-defined behavior, , Implementation-defined behavior, cpp, The C Preprocessor}. @@ -209,7 +230,7 @@ behavior, cpp, The C Preprocessor}. @cite{The encoding of any of @code{wchar_t}, @code{char16_t}, and @code{char32_t} where the corresponding standard encoding macro (@code{__STDC_ISO_10646__}, @code{__STDC_UTF_16__}, or -@code{__STDC_UTF_32__}) is not defined (C11 6.10.8.2).} +@code{__STDC_UTF_32__}) is not defined (C11 6.10.8.2, C23 6.10.10.3).} @xref{Implementation-defined behavior, , Implementation-defined behavior, cpp, The C Preprocessor}. @code{char16_t} and @@ -223,8 +244,8 @@ respectively. @itemize @bullet @item -@cite{Any extended integer types that exist in the implementation (C99 -and C11 6.2.5).} +@cite{Any extended integer types that exist in the implementation (C99, +C11 and C23 6.2.5).} GCC does not support any extended integer types. @c The __mode__ attribute might create types of precisions not @@ -240,11 +261,12 @@ two's complement, or one's complement, and whether the extraordinary value is a trap representation or an ordinary value (C99 and C11 6.2.6.2).} GCC supports only two's complement integer types, and all bit patterns -are ordinary values. +are ordinary values. C23 requires signed integer types to be two's +complement. @item @cite{The rank of any extended integer type relative to another extended -integer type with the same precision (C99 and C11 6.3.1.1).} +integer type with the same precision (C99 and C11 6.3.1.1, C23 6.3.2.1).} GCC does not support any extended integer types. @c If it did, there would only be one of each precision and signedness. @@ -252,14 +274,14 @@ GCC does not support any extended integer types. @item @cite{The result of, or the signal raised by, converting an integer to a signed integer type when the value cannot be represented in an object of -that type (C90 6.2.1.2, C99 and C11 6.3.1.3).} +that type (C90 6.2.1.2, C99 and C11 6.3.1.3, C23 6.3.2.3).} For conversion to a type of width @math{N}, the value is reduced modulo @math{2^N} to be within range of the type; no signal is raised. @item @cite{The results of some bitwise operations on signed integers (C90 -6.3, C99 and C11 6.5).} +6.3, C99 and C11 6.5, C23 6.5.1).} Bitwise operators act on the representation of the value including both the sign and value bits, where the sign bit is considered @@ -267,7 +289,7 @@ immediately above the highest-value value bit. Signed @samp{>>} acts on negative numbers by sign extension. As an extension to the C language, GCC does not use the latitude given in -C99 and C11 only to treat certain aspects of signed @samp{<<} as undefined. +C99 and later to treat certain aspects of signed @samp{<<} as undefined. However, @option{-fsanitize=shift} (and @option{-fsanitize=undefined}) will diagnose such cases. They are also diagnosed where constant expressions are required. @@ -275,7 +297,7 @@ expressions are required. @item @cite{The sign of the remainder on integer division (C90 6.3.5).} -GCC always follows the C99 and C11 requirement that the result of division is +GCC always follows the C99 and later requirement that the result of division is truncated towards zero. @end itemize @@ -287,34 +309,46 @@ truncated towards zero. @item @cite{The accuracy of the floating-point operations and of the library functions in @code{<math.h>} and @code{<complex.h>} that return floating-point -results (C90, C99 and C11 5.2.4.2.2).} +results (C90, C99 and C11 5.2.4.2.2, C23 5.3.5.3.3).} The accuracy is unknown. @item @cite{The rounding behaviors characterized by non-standard values of @code{FLT_ROUNDS} -(C90, C99 and C11 5.2.4.2.2).} +(C90, C99 and C11 5.2.4.2.2, C23 5.3.5.3.3).} + +GCC does not use such values. + +@item +@cite{The evaluation methods characterized by non-standard negative +values of @code{FLT_EVAL_METHOD} (C99 and C11 5.2.4.2.2, C23 5.3.5.3.3).} GCC does not use such values. @item @cite{The evaluation methods characterized by non-standard negative -values of @code{FLT_EVAL_METHOD} (C99 and C11 5.2.4.2.2).} +values of @code{DEC_EVAL_METHOD} (C23 5.3.5.3.4).} GCC does not use such values. @item +@cite{If decimal floating types are supported (C23 6.2.5).} + +These are supported for certain AArch64, i386, x86-64, PowerPC and +S/390 targets only. + +@item @cite{The direction of rounding when an integer is converted to a floating-point number that cannot exactly represent the original -value (C90 6.2.1.3, C99 and C11 6.3.1.4).} +value (C90 6.2.1.3, C99 and C11 6.3.1.4, C23 6.3.2.4).} C99 Annex F is followed. @item @cite{The direction of rounding when a floating-point number is converted to a narrower floating-point number (C90 6.2.1.4, C99 and C11 -6.3.1.5).} +6.3.1.5, C23 6.3.2.5).} C99 Annex F is followed. @@ -322,13 +356,14 @@ C99 Annex F is followed. @cite{How the nearest representable value or the larger or smaller representable value immediately adjacent to the nearest representable value is chosen for certain floating constants (C90 6.1.3.1, C99 and C11 -6.4.4.2).} +6.4.4.2, C23 6.4.5.3).} C99 Annex F is followed. @item @cite{Whether and how floating expressions are contracted when not -disallowed by the @code{FP_CONTRACT} pragma (C99 and C11 6.5).} +disallowed by the @code{FP_CONTRACT} pragma (C99 and C11 6.5, C23 +6.5.1).} Expressions are currently only contracted if @option{-ffp-contract=fast}, @option{-funsafe-math-optimizations} or @option{-ffast-math} are used. @@ -336,7 +371,7 @@ This is subject to change. @item @cite{The default state for the @code{FENV_ACCESS} pragma (C99 and C11 -7.6.1).} +7.6.1, C23 7.6.2).} This pragma is not implemented, but the default is to ``off'' unless @option{-frounding-math} is used and @option{-fno-trapping-math} is not @@ -344,15 +379,15 @@ in which case it is ``on''. @item @cite{Additional floating-point exceptions, rounding modes, environments, -and classifications, and their macro names (C99 and C11 7.6, C99 and -C11 7.12).} +and classifications, and their macro names (C99, C11 and C23 7.6, C99, +C11 and C23 7.12).} This is dependent on the implementation of the C library, and is not defined by GCC itself. @item @cite{The default state for the @code{FP_CONTRACT} pragma (C99 and C11 -7.12.2).} +7.12.2, C23 7.12.3).} This pragma is not implemented. Expressions are currently only contracted if @option{-ffp-contract=fast}, @@ -377,13 +412,32 @@ defined by GCC itself. @end itemize +@node Constant expressions implementation +@section Constant expressions + +@itemize @bullet +@item +@cite{Whether or not an expression not explicitly sanctioned by this +document is an extended constant expression, whether or not such +extended constant expressions can be used in the same contexts as this +document, and whether or not such extended constant expressions can +affect potentially detectable semantic changes in the program (C23 +6.6).} + +The only extended constant expressions are those using other GNU +extensions to the C language. Such extended constant expressions +include integer constant expressions and arithmetic constant +expressions. + +@end itemize + @node Arrays and pointers implementation @section Arrays and Pointers @itemize @bullet @item @cite{The result of converting a pointer to an integer or -vice versa (C90 6.3.4, C99 and C11 6.3.2.3).} +vice versa (C90 6.3.4, C99 and C11 6.3.2.3, C23 6.3.3.3).} A cast from pointer to integer discards most-significant bits if the pointer representation is larger than the integer type, @@ -410,7 +464,7 @@ C99 and C11 6.5.6/8. @item @cite{The size of the result of subtracting two pointers to elements -of the same array (C90 6.3.6, C99 and C11 6.5.6).} +of the same array (C90 6.3.6, C99 and C11 6.5.6, C23 6.5.7).} The value is as specified in the standard and the type is determined by the ABI@. @@ -423,7 +477,8 @@ by the ABI@. @itemize @bullet @item @cite{The extent to which suggestions made by using the @code{register} -storage-class specifier are effective (C90 6.5.1, C99 and C11 6.7.1).} +storage-class specifier are effective (C90 6.5.1, C99 and C11 6.7.1, +C23 6.7.2).} The @code{register} specifier affects code generation only in these ways: @@ -448,7 +503,7 @@ in registers unless they are marked @code{register}. @item @cite{The extent to which suggestions made by using the inline function -specifier are effective (C99 and C11 6.7.4).} +specifier are effective (C99 and C11 6.7.4, C23 6.7.5).} GCC will not inline any functions if the @option{-fno-inline} option is used or if @option{-O0} is used. Otherwise, GCC may still be unable to @@ -472,7 +527,8 @@ may be a trap representation. @item @cite{Whether a ``plain'' @code{int} bit-field is treated as a @code{signed int} bit-field or as an @code{unsigned int} bit-field -(C90 6.5.2, C90 6.5.2.1, C99 and C11 6.7.2, C99 and C11 6.7.2.1).} +(C90 6.5.2, C90 6.5.2.1, C99 and C11 6.7.2, C23 6.7.3, C99 and C11 +6.7.2.1, C23 6.7.3.2).} @opindex funsigned-bitfields By default it is treated as @code{signed int} but this may be changed @@ -480,37 +536,38 @@ by the @option{-funsigned-bitfields} option. @item @cite{Allowable bit-field types other than @code{_Bool}, @code{signed int}, -and @code{unsigned int} (C99 and C11 6.7.2.1).} +and @code{unsigned int} (C99 and C11 6.7.2.1, C23 6.7.3.2).} Other integer types, such as @code{long int}, and enumerated types are permitted even in strictly conforming mode. @item -@cite{Whether atomic types are permitted for bit-fields (C11 6.7.2.1).} +@cite{Whether atomic types are permitted for bit-fields (C11 6.7.2.1, +C23 6.7.3.2).} Atomic types are not permitted for bit-fields. @item @cite{Whether a bit-field can straddle a storage-unit boundary (C90 -6.5.2.1, C99 and C11 6.7.2.1).} +6.5.2.1, C99 and C11 6.7.2.1, C23 6.7.3.2).} Determined by ABI@. @item @cite{The order of allocation of bit-fields within a unit (C90 -6.5.2.1, C99 and C11 6.7.2.1).} +6.5.2.1, C99 and C11 6.7.2.1, C23 6.7.3.2).} Determined by ABI@. @item @cite{The alignment of non-bit-field members of structures (C90 -6.5.2.1, C99 and C11 6.7.2.1).} +6.5.2.1, C99 and C11 6.7.2.1, C23 6.7.3.2).} Determined by ABI@. @item @cite{The integer type compatible with each enumerated type (C90 -6.5.2.2, C99 and C11 6.7.2.2).} +6.5.2.2, C99 and C11 6.7.2.2, C23 6.7.3.3).} @opindex fshort-enums Normally, the type is @code{unsigned int} if there are no negative @@ -538,7 +595,7 @@ determined by the ABI@. @itemize @bullet @item @cite{What constitutes an access to an object that has volatile-qualified -type (C90 6.5.3, C99 and C11 6.7.3).} +type (C90 6.5.3, C99 and C11 6.7.3, C23 6.7.4).} Such an object is normally accessed by pointers and used for accessing hardware. In most expressions, it is intuitively obvious what is a read @@ -584,6 +641,32 @@ object's declared type were @code{volatile S}. @end itemize +@node Types implementation +@section Types + +@itemize @bullet +@item +@cite{A program forms the composite type of an enumerated type and a +non-enumeration integer type (C23 6.2.7).} + +The composite type is the enumerated type. + +@item +@cite{Whether or not it is supported for a declaration for which a +type is inferred to contain a pointer, array, or function declarator +(C23 6.7.10).} + +This is not supported. + +@item +@cite{Whether or not it is supported for a declaration for which a +type is inferred to contain no or more than one declarators (C23 +6.7.10).} + +This is not supported. + +@end itemize + @node Declarators implementation @section Declarators @@ -618,48 +701,70 @@ implementation-defined behavior. @itemize @bullet @item @cite{The locations within @code{#pragma} directives where header name -preprocessing tokens are recognized (C11 6.4, C11 6.4.7).} +preprocessing tokens are recognized (C11 and C23 6.4, C11 6.4.7, C23 +6.4.8).} @item @cite{How sequences in both forms of header names are mapped to headers -or external source file names (C90 6.1.7, C99 and C11 6.4.7).} +or external source file names (C90 6.1.7, C99 and C11 6.4.7, C23 +6.4.8).} @item @cite{Whether the value of a character constant in a constant expression that controls conditional inclusion matches the value of the same character -constant in the execution character set (C90 6.8.1, C99 and C11 6.10.1).} +constant in the execution character set (C90 6.8.1, C99 and C11 +6.10.1, C23 6.10.2).} @item @cite{Whether the value of a single-character character constant in a constant expression that controls conditional inclusion may have a -negative value (C90 6.8.1, C99 and C11 6.10.1).} +negative value (C90 6.8.1, C99 and C11 6.10.1, C23 6.10.2).} @item @cite{The places that are searched for an included @samp{<>} delimited header, and how the places are specified or the header is -identified (C90 6.8.2, C99 and C11 6.10.2).} +identified (C90 6.8.2, C99 and C11 6.10.2, C23 6.10.3).} @item @cite{How the named source file is searched for in an included @samp{""} -delimited header (C90 6.8.2, C99 and C11 6.10.2).} +delimited header (C90 6.8.2, C99 and C11 6.10.2, C23 6.10.3).} + +@item +@cite{How the named resource file is searched for in an embedded @samp{""} +delimited resource name (C23 6.10.4).} @item @cite{The method by which preprocessing tokens (possibly resulting from macro expansion) in a @code{#include} directive are combined into a header -name (C90 6.8.2, C99 and C11 6.10.2).} +name (C90 6.8.2, C99 and C11 6.10.2, C23 6.10.3).} @item @cite{The nesting limit for @code{#include} processing (C90 6.8.2, C99 -and C11 6.10.2).} +and C11 6.10.2, C23 6.10.3).} + +@item +@cite{The method by which preprocessing tokens (possibly resulting +from macro expansion) in a @code{#embed} directive are combined into a +resource name (C23 6.10.4).} + +@item +@cite{The mapping between a resource's data and the values of the +integer constant expressions, if any, in the replacement of a +@code{#embed} directive (C23 6.10.4).} + +@item +@cite{The width of a resource located by the @code{#embed} directive +(C23 6.10.4).} @item @cite{Whether the @samp{#} operator inserts a @samp{\} character before the @samp{\} character that begins a universal character name in a -character constant or string literal (C99 and C11 6.10.3.2).} +character constant or string literal (C99 and C11 6.10.3.2, C23 +6.10.5.3).} @item @cite{The behavior on each recognized non-@code{STDC #pragma} -directive (C90 6.8.6, C99 and C11 6.10.6).} +directive (C90 6.8.6, C99 and C11 6.10.6, C23 6.10.8).} @xref{Pragmas, , Pragmas, cpp, The C Preprocessor}, for details of pragmas accepted by GCC on all targets. @xref{Pragmas, , Pragmas @@ -668,7 +773,7 @@ Accepted by GCC}, for details of target-specific pragmas. @item @cite{The definitions for @code{__DATE__} and @code{__TIME__} when respectively, the date and time of translation are not available (C90 -6.8.8, C99 6.10.8, C11 6.10.8.1).} +6.8.8, C99 6.10.8, C11 6.10.8.1, C23 6.10.10.2).} @end itemize @@ -681,7 +786,7 @@ of the C library, and are not defined by GCC itself. @itemize @bullet @item @cite{The null pointer constant to which the macro @code{NULL} expands -(C90 7.1.6, C99 7.17, C11 7.19).} +(C90 7.1.6, C99 7.17, C11 7.19, C23 7.21).} In @code{<stddef.h>}, @code{NULL} expands to @code{((void *)0)}. GCC does not provide the other headers which define @code{NULL} and some @@ -696,14 +801,15 @@ library implementations may use other definitions in those headers. @item @cite{The values or expressions assigned to the macros specified in the headers @code{<float.h>}, @code{<limits.h>}, and @code{<stdint.h>} -(C90, C99 and C11 5.2.4.2, C99 7.18.2, C99 7.18.3, C11 7.20.2, C11 7.20.3).} +(C90, C99 and C11 5.2.4.2, C23 5.3.5.3, C99 7.18.2, C99 7.18.3, C11 +7.20.2, C11 7.20.3, C23 7.22).} Determined by ABI@. @item @cite{The result of attempting to indirectly access an object with automatic or thread storage duration from a thread other than the one -with which it is associated (C11 6.2.4).} +with which it is associated (C11 and C23 6.2.4).} Such accesses are supported, subject to the same requirements for synchronization for concurrent accesses as for concurrent accesses to @@ -711,14 +817,14 @@ any object. @item @cite{The number, order, and encoding of bytes in any object -(when not explicitly specified in this International Standard) (C99 -and C11 6.2.6.1).} +(when not explicitly specified in this International Standard) (C99, +C11 and C23 6.2.6.1).} Determined by ABI@. @item @cite{Whether any extended alignments are supported and the contexts -in which they are supported (C11 6.2.8).} +in which they are supported (C11 and C23 6.2.8).} Extended alignments up to @math{2^{28}} (bytes) are supported for objects of automatic storage duration. Alignments supported for @@ -727,13 +833,13 @@ ABI. @item @cite{Valid alignment values other than those returned by an _Alignof -expression for fundamental types, if any (C11 6.2.8).} +expression for fundamental types, if any (C11 and C23 6.2.8).} Valid alignments are powers of 2 up to and including @math{2^{28}}. @item @cite{The value of the result of the @code{sizeof} and @code{_Alignof} -operators (C90 6.3.3.4, C99 and C11 6.5.3.4).} +operators (C90 6.3.3.4, C99 and C11 6.5.3.4, C23 6.5.4.5).} Determined by ABI@. diff --git a/gcc/doc/install.texi b/gcc/doc/install.texi index b5509ff..80ee2cd 100644 --- a/gcc/doc/install.texi +++ b/gcc/doc/install.texi @@ -350,6 +350,12 @@ documentation including the target @code{SYSTEM} definition module. If Python3 is unavailable Modula-2 documentation will include a target independent version of the SYSTEM modules. +@item @anchor{gccrs-prerequisite}gccrs + +The official Rust compiler and Rust build system (cargo) are required for +building various parts of the gccrs frontend, until gccrs can compile them +by itself. The minimum supported Rust version is 1.49. + @item A ``working'' POSIX compatible shell, or GNU bash Necessary when running @command{configure} because some @@ -625,6 +631,9 @@ building the documentation without error, but you may still want to install a newer release to get the best appearance and usability of the generated manuals. +Also note that Texinfo older than version 7.1 may throw incorrect build +warnings, though the generated documentation is correct. + @item @TeX{} (any working version) Necessary for running @command{texi2dvi} and @command{texi2pdf}, which @@ -1336,9 +1345,13 @@ default set of libraries is selected based on the value of @item amdgcn*-*-* @var{list} is a comma separated list of ISA names (allowed values: -@code{gfx900}, @code{gfx906}, @code{gfx908}, @code{gfx90a}, @code{gfx90c}, -@code{gfx1030}, @code{gfx1036}, @code{gfx1100}, @code{gfx1103}). -It ought not include the name of the default +@code{gfx900}, @code{gfx902}, @code{gfx904}, @code{gfx906}, @code{gfx908}, +@code{gfx909}, @code{gfx90a}, @code{gfx90c}, @code{gfx942}, @code{gfx950}, +@code{gfx9-generic}, @code{gfx9-4-generic}, @code{gfx1030}, @code{gfx1031}, +@code{gfx1032}, @code{gfx1033}, @code{gfx1034}, @code{gfx1035}, @code{gfx1036}, +@code{gfx10-3-generic}, @code{gfx1100}, @code{gfx1101}, @code{gfx1102}, +@code{gfx1103}, @code{gfx1150}, @code{gfx1151}, @code{gfx1152}, @code{gfx1153}, +@code{gfx11-generic}). It ought not include the name of the default ISA, specified via @option{--with-arch}. If @var{list} is empty, then there will be no multilibs and only the default run-time library will be built. If @var{list} is @code{default} or @option{--with-multilib-list=} is not @@ -3138,6 +3151,13 @@ Removes any @option{-O}-started option from @code{BOOT_CFLAGS}, and adds @itemx @samp{bootstrap-Og} Analogous to @code{bootstrap-O1}. +@item @samp{bootstrap-native} +@itemx @samp{bootstrap-native} +Optimize the compiler code for the build host, if supported by the +architecture. Note this only affects the compiler, not the targeted +code. If you want the later, choose options suitable to the target you +are looking for. For example @samp{--with-cpu} would be a good starting point. + @item @samp{bootstrap-lto} Enables Link-Time Optimization for host tools during bootstrapping. @samp{BUILD_CONFIG=bootstrap-lto} is equivalent to adding @@ -4047,9 +4067,10 @@ By default, multilib support is built for @code{gfx900}, @code{gfx906}, requires LLVM 15 or newer. LLVM 13.0.1 or LLVM 14 can be used by specifying a @code{--with-multilib-list=} that does not list any GFX 11 device nor @code{gfx1036}. At least LLVM 16 is required for @code{gfx1150} and -@code{gfx1151}, LLVM 19 for the generic @code{gfx9-generic}, -@code{gfx10-3-generic}, and @code{gfx11-generic} targets and for -@code{gfx1152}, while LLVM 20 is required for @code{gfx1153}. +@code{gfx1151}, LLVM 18 for @code{gfx942}, LLVM 19 for the generic +@code{gfx9-generic}, @code{gfx9-4-generic}, @code{gfx10-3-generic}, and +@code{gfx11-generic} targets and for @code{gfx1152}, while LLVM 20 is required +for @code{gfx950} and @code{gfx1153}. The supported ISA architectures are listed in the GCC manual. The generic ISA targets @code{gfx9-generic}, @code{gfx10-3-generic}, and diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi index 2397e5d..9a1aa37 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 @@ -266,7 +266,7 @@ in the following sections. -Wnoexcept -Wnoexcept-type -Wnon-virtual-dtor -Wpessimizing-move -Wno-placement-new -Wplacement-new=@var{n} -Wrange-loop-construct -Wredundant-move -Wredundant-tags --Wreorder -Wregister +-Wreorder -Wregister -Wno-sfinae-incomplete -Wstrict-null-sentinel -Wno-subobject-linkage -Wtemplates -Wno-non-template-friend -Wold-style-cast -Woverloaded-virtual -Wno-pmf-conversions -Wself-move -Wsign-promo @@ -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 @@ -312,7 +312,7 @@ Objective-C and Objective-C++ Dialects}. -fdiagnostics-show-location=@r{[}once@r{|}every-line@r{]} -fdiagnostics-color=@r{[}auto@r{|}never@r{|}always@r{]} -fdiagnostics-urls=@r{[}auto@r{|}never@r{|}always@r{]} --fdiagnostics-format=@r{[}text@r{|}sarif-stderr@r{|}sarif-file@r{|}json@r{|}json-stderr@r{|}json-file@r{]} +-fdiagnostics-format=@r{[}text@r{|}sarif-stderr@r{|}sarif-file@r{]} -fdiagnostics-add-output=@var{DIAGNOSTICS-OUTPUT-SPEC} -fdiagnostics-set-output=@var{DIAGNOSTICS-OUTPUT-SPEC} -fno-diagnostics-json-formatting @@ -340,7 +340,7 @@ Objective-C and Objective-C++ Dialects}. -w -Wextra -Wall -Wabi=@var{n} -Waddress -Wno-address-of-packed-member -Waggregate-return -Walloc-size -Walloc-size-larger-than=@var{byte-size} -Walloc-zero --Walloca -Walloca-larger-than=@var{byte-size} +-Walloca -Walloca-larger-than=@var{byte-size} -Wauto-profile -Wno-aggressive-loop-optimizations -Warith-conversion -Warray-bounds -Warray-bounds=@var{n} -Warray-compare @@ -353,7 +353,7 @@ Objective-C and Objective-C++ Dialects}. -Wno-builtin-macro-redefined -Wc90-c99-compat -Wc99-c11-compat -Wc11-c23-compat -Wc23-c2y-compat -Wc++-compat -Wc++11-compat -Wc++14-compat -Wc++17-compat --Wc++20-compat +-Wc++20-compat -Wc++26-compat -Wno-c++11-extensions -Wno-c++14-extensions -Wno-c++17-extensions -Wno-c++20-extensions -Wno-c++23-extensions -Wcalloc-transposed-args @@ -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 @@ -509,6 +513,7 @@ Objective-C and Objective-C++ Dialects}. -Wno-analyzer-tainted-divisor -Wno-analyzer-tainted-offset -Wno-analyzer-tainted-size +-Wno-analyzer-throw-of-unexpected-type -Wanalyzer-symbol-too-complex -Wanalyzer-too-complex -Wno-analyzer-undefined-behavior-ptrdiff @@ -568,13 +573,13 @@ Objective-C and Objective-C++ Dialects}. -fmin-function-alignment=[@var{n}] -fno-allocation-dce -fallow-store-data-races -fassociative-math -fauto-profile -fauto-profile[=@var{path}] --fauto-inc-dec -fbranch-probabilities +-fauto-profile-inlining -fauto-inc-dec -fbranch-probabilities -fcaller-saves -fcombine-stack-adjustments -fconserve-stack -ffold-mem-offsets -fcompare-elim -fcprop-registers -fcrossjumping -fcse-follow-jumps -fcse-skip-blocks -fcx-fortran-rules --fcx-limited-range +-fcx-limited-range -fcx-method -fdata-sections -fdce -fdelayed-branch -fdelete-null-pointer-checks -fdevirtualize -fdevirtualize-speculatively -fdevirtualize-at-ltrans -fdse @@ -589,7 +594,7 @@ Objective-C and Objective-C++ Dialects}. -finline-functions -finline-functions-called-once -finline-limit=@var{n} -finline-small-functions -fipa-modref -fipa-cp -fipa-cp-clone -fipa-bit-cp -fipa-vrp -fipa-pta -fipa-profile -fipa-pure-const --fipa-reference -fipa-reference-addressable +-fipa-reference -fipa-reference-addressable -fipa-reorder-for-locality -fipa-stack-alignment -fipa-icf -fira-algorithm=@var{algorithm} -flate-combine-instructions -flifetime-dse -flive-patching=@var{level} -fira-region=@var{region} -fira-hoist-pressure @@ -638,8 +643,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 +676,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 +996,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 @@ -1262,7 +1268,7 @@ See RS/6000 and PowerPC Options. -mfence-tso -mno-fence-tso -mdiv -mno-div -misa-spec=@var{ISA-spec-string} --march=@var{ISA-string} +-march=@var{ISA-string|Profiles|Profiles_ISA-string|CPU/processor string} -mtune=@var{processor-string} -mpreferred-stack-boundary=@var{num} -msmall-data-limit=@var{N-bytes} @@ -1490,8 +1496,8 @@ See RS/6000 and PowerPC Options. -mamx-tile -mamx-int8 -mamx-bf16 -muintr -mhreset -mavxvnni -mamx-fp8 -mavx512fp16 -mavxifma -mavxvnniint8 -mavxneconvert -mcmpccxadd -mamx-fp16 -mprefetchi -mraoint -mamx-complex -mavxvnniint16 -msm3 -msha512 -msm4 -mapxf --musermsr -mavx10.1 -mavx10.1-256 -mavx10.1-512 -mevex512 -mavx10.2 --mamx-avx512 -mamx-tf32 -mamx-transpose -mmovrs -mamx-movrs +-musermsr -mavx10.1 -mavx10.2 -mamx-avx512 -mamx-tf32 -mamx-transpose -mmovrs +-mamx-movrs -mcldemote -mms-bitfields -mno-align-stringops -minline-all-stringops -minline-stringops-dynamically -mstringop-strategy=@var{alg} -mkl -mwidekl @@ -2194,6 +2200,7 @@ those that have already been displayed. If @option{--help} is also specified anywhere on the command line then this takes precedence over any @option{--help=} option. +@opindex Q If the @option{-Q} option appears on the command line before the @option{--help=} option, then the descriptive text displayed by @option{--help=} is changed. Instead of describing the displayed @@ -2433,8 +2440,8 @@ ISO C99. This standard is substantially completely supported, modulo bugs and floating-point issues (mainly but not entirely relating to optional C99 features from Annexes F and G). See -@w{@uref{https://gcc.gnu.org/c99status.html}} for more information. The -names @samp{c9x} and @samp{iso9899:199x} are deprecated. +@w{@uref{https://gcc.gnu.org/projects/c-status.html}} for more information. +The names @samp{c9x} and @samp{iso9899:199x} are deprecated. @item c11 @itemx c1x @@ -2613,8 +2620,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. @@ -2999,12 +3006,18 @@ in C++14 and up. Version 18, which first appeared in G++ 13, fixes manglings of lambdas that have additional context. -Version 19, which first appeared in G++ 14, fixes manglings of structured -bindings to include ABI tags. +Version 19, which first appeared in G++ 14, fixes manglings of +structured bindings to include ABI tags, handling of cv-qualified +[[no_unique_address]] members, and adds mangling of C++20 constraints +on function templates. Version 20, which first appeared in G++ 15, fixes manglings of lambdas in static data member initializers. +Version 21, which first appeared in G++ 16, fixes unnecessary captures +in noexcept lambdas (c++/119764) and layout of a base class +with all explicitly defaulted constructors (c++/120012). + See also @option{-Wabi}. @opindex fabi-compat-version @@ -3284,6 +3297,50 @@ Enable support for the C++ coroutines extension (experimental). Permit the C++ front end to note all candidates during overload resolution failure, including when a deleted function is selected. +@item -fdump-lang- +@itemx -fdump-lang-@var{switch} +@itemx -fdump-lang-@var{switch}-@var{options} +@itemx -fdump-lang-@var{switch}-@var{options}=@var{filename} +Control the dumping of C++-specific information. The @var{options} +and @var{filename} portions behave as described in the +@option{-fdump-tree} option. The following @var{switch} values are +accepted: + +@table @samp +@item all +Enable all of the below. + +@opindex fdump-lang-class +@item class +Dump class hierarchy information. Virtual table information is emitted +unless '@option{slim}' is specified. + +@opindex fdump-lang-module +@item module +Dump module information. Options @option{lineno} (locations), +@option{graph} (reachability), @option{blocks} (clusters), +@option{uid} (serialization), @option{alias} (mergeable), +@option{asmname} (Elrond), @option{eh} (mapper) & @option{vops} +(macros) may provide additional information. + +@opindex fdump-lang-raw +@item raw +Dump the raw internal tree data. + +@opindex fdump-lang-tinst +@item tinst +Dump the sequence of template instantiations, indented to show the +depth of recursion. The @option{lineno} option adds the source +location where the instantiation was triggered, and the +@option{details} option also dumps pre-instantiation substitutions +such as those performed during template argument deduction. + +Lines in the .tinst dump start with @samp{I} for an instantiation, +@samp{S} for another substitution, and @samp{R[IS]} for the reopened +context of a deferred instantiation. + +@end table + @opindex fno-elide-constructors @opindex felide-constructors @item -fno-elide-constructors @@ -3335,7 +3392,8 @@ aliases, the default is @option{-fno-extern-tls-init}. @item -ffold-simple-inlines @itemx -fno-fold-simple-inlines Permit the C++ frontend to fold calls to @code{std::move}, @code{std::forward}, -@code{std::addressof} and @code{std::as_const}. In contrast to inlining, this +@code{std::addressof}, @code{std::to_underlying} +and @code{std::as_const}. In contrast to inlining, this means no debug information will be generated for such calls. Since these functions are rarely interesting to debug, this flag is enabled by default unless @option{-fno-inline} is active. @@ -3576,12 +3634,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} @@ -3751,6 +3816,23 @@ Warn when a type with an ABI tag is used in a context that does not have that ABI tag. See @ref{C++ Attributes} for more information about ABI tags. +@opindex Wabbreviated-auto-in-template-arg +@opindex Wno-abbreviated-auto-in-template-arg +@item -Wno-abbreviated-auto-in-template-arg +Disable the error for an @code{auto} placeholder type used within a +template argument list to declare a C++20 abbreviated function +template, e.g. + +@smallexample +void f(S<auto>); +@end smallexample + +This feature was proposed in the Concepts TS, but was not adopted into +C++20; in the standard, a placeholder in a parameter declaration must +appear as a decl-specifier. The error can also be reduced to a +warning by @option{-fpermissive} or +@option{-Wno-error=abbreviated-auto-in-template-arg}. + @opindex Wcomma-subscript @opindex Wno-comma-subscript @item -Wcomma-subscript @r{(C++ and Objective-C++ only)} @@ -4383,6 +4465,20 @@ to filter out those warnings. Disable the warning about the case when an exception handler is shadowed by another handler, which can point out a wrong ordering of exception handlers. +@opindex Wsfinae-incomplete +@opindex Wno-sfinae-incomplete +Warn about a class that is found to be incomplete, or a function with +auto return type that has not yet been deduced, in a context where +that causes substitution failure rather than an error, and then the +class or function is defined later in the translation unit. This is +problematic because template instantiations or concept checks could +have different results if they first occur either before or after the +definition. + +This warning is enabled by default. @option{-Wsfinae-incomplete=2} +adds a warning at the point of substitution failure, to make it easier +to track down problems flagged by the default mode. + @opindex Wstrict-null-sentinel @opindex Wno-strict-null-sentinel @item -Wstrict-null-sentinel @r{(C++ and Objective-C++ only)} @@ -4689,11 +4785,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 @@ -5884,8 +5975,7 @@ column numbers, such as @command{dejagnu}. @opindex fdiagnostics-column-unit @item -fdiagnostics-column-unit=@var{UNIT} Select the units for the column number. This affects traditional diagnostics -(in the absence of @option{-fno-show-column}), as well as JSON format -diagnostics if requested. +(in the absence of @option{-fno-show-column}). The default @var{UNIT}, @samp{display}, considers the number of display columns occupied by each character. This may be larger than the number @@ -5961,8 +6051,7 @@ is set to @samp{C}, in which case the default is @samp{ascii}. @opindex fdiagnostics-format @item -fdiagnostics-format=@var{FORMAT} Select a different format for printing diagnostics. -@var{FORMAT} is @samp{text}, @samp{sarif-stderr}, @samp{sarif-file}, -@samp{json}, @samp{json-stderr}, or @samp{json-file}. +@var{FORMAT} is @samp{text}, @samp{sarif-stderr} or @samp{sarif-file}. Using this option replaces any additional ``output sinks'' added by @option{-fdiagnostics-add-output=}, or that set by @@ -5974,14 +6063,6 @@ The @samp{sarif-stderr} and @samp{sarif-file} formats both emit diagnostics in SARIF Version 2.1.0 format, either to stderr, or to a file named @file{@var{source}.sarif}, respectively. -The various @samp{json}, @samp{json-stderr}, and @samp{json-file} values -are deprecated and refer to a legacy JSON-based output format. -The @samp{json} format is a synonym for @samp{json-stderr}. -The @samp{json-stderr} and @samp{json-file} formats are identical, apart from -where the JSON is emitted to. With @samp{json-stderr}, the JSON is emitted -to stderr, whereas with @samp{json-file} it is written to -@file{@var{source}.gcc.json}. - @opindex fdiagnostics-add-output @item -fdiagnostics-add-output=@var{DIAGNOSTICS-OUTPUT-SPEC} Add an additional ``output sink'' for emitting diagnostics. @@ -6044,6 +6125,11 @@ Specify the filename to write the SARIF output to, potentially with a leading absolute or relative path. If not specified, it defaults to @file{@var{source}.sarif}. +@item serialization=@r{[}json@r{]} +Specify the serialization format to use when writing out the SARIF. +Currently this can only be @code{json}, but is present as an +extension point for experimenting with other serializations. + @item version=@r{[}2.1@r{|}2.2-prerelease@r{]} Specify the version of SARIF to use for the output. If not specified, defaults to 2.1. @code{2.2-prerelease} uses an unofficial draft of the @@ -6052,6 +6138,70 @@ in this release. @end table +There is also this key intended for use by GCC developers, rather than +end-users, and subject to change or removal without notice: + +@table @gcctabopt + +@item state-graphs=@r{[}yes@r{|}no@r{]} +This is a debugging feature and defaults to @code{no}. +If @code{state-graphs=yes}, then attempt to capture detailed state +information from @option{-fanalyzer} in the generated SARIF. + +@end table + +@item experimental-html +Emit diagnostics to a file in HTML format. This scheme is experimental, +and may go away in future GCC releases. The keys and details of the output +are also subject to change. + +Supported keys are: + +@table @gcctabopt + +@item css=@r{[}yes@r{|}no@r{]} +Add an embedded <style> to the generated HTML. Defaults to yes. + +@item file=@var{FILENAME} +Specify the filename to write the HTML output to, potentially with a +leading absolute or relative path. If not specified, it defaults to +@file{@var{source}.html}. + +@item javascript=@r{[}yes@r{|}no@r{]} +Add an embedded <script> to the generated HTML providing a barebones UI +for viewing results. Defaults to yes. + +@end table + +There are also these keys intended for use by GCC developers, rather than +end-users, and subject to change or removal without notice: + +@table @gcctabopt + +@item show-state-diagrams=@r{[}yes@r{|}no@r{]} +This is a debugging feature and defaults to @code{no}. +If @code{show-state-diagrams=yes}, then attempt to use @command{dot} to +generate SVG diagrams in the generated HTML, visualizing the state at each +event in a diagnostic path. +These are visible by pressing ``j'' and ``k'' to single-step forward and +backward through events. Enabling this option will slow down +HTML generation. + +@item show-state-diagrams-dot-src=@r{[}yes@r{|}no@r{]} +This is a debugging feature and defaults to @code{no}. +If @code{show-state-diagrams-dot-src=yes} +then if @code{show-state-diagrams=yes}, +the generated state diagrams will also show the .dot source input to +GraphViz used for the diagram. + +@item show-state-diagrams-sarif=@r{[}yes@r{|}no@r{]} +This is a debugging feature and defaults to @code{no}. +If @code{show-state-diagrams-sarif=yes} +then if @code{show-state-diagrams=yes}, the generated state diagrams will +also show a SARIF representation of the state. + +@end table + @end table For example, @@ -6071,7 +6221,7 @@ In EBNF: @var{diagnostics-output-specifier} = @var{diagnostics-output-name} | @var{diagnostics-output-name}, ":", @var{key-value-pairs}; -@var{diagnostics-output-name} = "text" | "sarif"; +@var{diagnostics-output-name} = "text" | "sarif" | "experimental-html"; @var{key-value-pairs} = @var{key-value-pair} | @var{key-value-pair} "," @var{key-value-pairs}; @@ -6095,11 +6245,8 @@ replaces all existing output sinks, such as from @option{-fdiagnostics-format=}, @opindex fdiagnostics-json-formatting @item -fno-diagnostics-json-formatting By default, when JSON is emitted for diagnostics (via -@option{-fdiagnostics-format=sarif-stderr}, -@option{-fdiagnostics-format=sarif-file}, -@option{-fdiagnostics-format=json}, -@option{-fdiagnostics-format=json-stderr}, -@option{-fdiagnostics-format=json-file}), +@option{-fdiagnostics-format=sarif-stderr} or +@option{-fdiagnostics-format=sarif-file}), GCC will add newlines and indentation to visually emphasize the hierarchical structure of the JSON. @@ -6147,12 +6294,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 +6327,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 +6340,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 +6357,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 @@ -6312,6 +6460,7 @@ only by this flag, but it also downgrades some C and C++ diagnostics that have their own flag: @gccoptlist{ +-Wabbreviated-auto-in-template-arg @r{(C++ and Objective-C++ only)} -Wdeclaration-missing-parameter-type @r{(C and Objective-C only)} -Wimplicit-function-declaration @r{(C and Objective-C only)} -Wimplicit-int @r{(C and Objective-C only)} @@ -6499,7 +6648,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 +6752,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: - -@itemize @bullet +@opindex Wpsabi +@opindex Wno-psabi +@item -Wpsabi @r{(C, Objective-C, C++ and Objective-C++ only)} -@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: +@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. -@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 +7119,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)} @@ -8540,6 +8733,11 @@ larger. @item -Walloca This option warns on all uses of @code{alloca} in the source. +@opindex Wno-auto-profile +@opindex Wauto-profile +@item -Wauto-profile +Output warnings about auto-profile inconsistencies. + @opindex Walloca-larger-than= @opindex Wno-alloca-larger-than @item -Walloca-larger-than=@var{byte-size} @@ -8919,6 +9117,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 @@ -9487,6 +9690,12 @@ and ISO C++ 2017. This warning is enabled by @option{-Wall}. Warn about C++ constructs whose meaning differs between ISO C++ 2017 and ISO C++ 2020. This warning is enabled by @option{-Wall}. +@opindex Wc++26-compat +@opindex Wno-c++26-compat +@item -Wc++26-compat @r{(C++ and Objective-C++ only)} +Warn about C++ constructs whose meaning differs between ISO C++ 2023 +and upcoming ISO C++ 2026. This warning is enabled by @option{-Wall}. + @opindex Wc++11-extensions @opindex Wno-c++11-extensions @item -Wno-c++11-extensions @r{(C++ and Objective-C++ only)} @@ -10060,8 +10269,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 @@ -10949,6 +11159,7 @@ Enabling this option effectively enables the following warnings: -Wanalyzer-tainted-divisor -Wanalyzer-tainted-offset -Wanalyzer-tainted-size +-Wanalyzer-throw-of-unexpected-type -Wanalyzer-undefined-behavior-ptrdiff -Wanalyzer-undefined-behavior-strtok -Wanalyzer-unsafe-call-within-signal-handler @@ -11600,6 +11811,17 @@ attacker could inject an out-of-bounds access. See @uref{https://cwe.mitre.org/data/definitions/129.html, CWE-129: Improper Validation of Array Index}. +@opindex Wanalyzer-throw-of-unexpected-type +@opindex Wno-analyzer-throw-of-unexpected-type +@item -Wno-analyzer-throw-of-unexpected-type +This warning requires @option{-fanalyzer} which enables it; +use @option{-Wno-analyzer-throw-of-unexpected-type} to disable it. +Dynamic exception specifications are only available in C++14 and earlier. + +This diagnostic warns for paths through the code in which a an exception +is thrown from a function with a dynamic exception specification where +the exception does not comply with the specification. + @opindex Wanalyzer-undefined-behavior-ptrdiff @opindex Wno-analyzer-undefined-behavior-ptrdiff @item -Wno-analyzer-undefined-behavior-ptrdiff @@ -12688,6 +12910,7 @@ complexity than at @option{-O}. -fipa-pure-const -fipa-reference -fipa-reference-addressable +-fivopts -fmerge-constants -fmove-loop-invariants -fmove-loop-stores @@ -12796,6 +13019,13 @@ by @option{-O2} and also turns on the following optimization flags: Reduce compilation time and make debugging produce the expected results. This is the default. +At @option{-O0}, GCC completely disables most optimization passes; +they are not run even if you explicitly enable them on the command +line, or are listed by @option{-Q --help=optimizers} as being enabled by +default. Many optimizations performed by GCC depend on code analysis +or canonicalization passes that are enabled by @option{-O}, and it would +not be useful to run individual optimization passes in isolation. + @opindex Os @item -Os Optimize for size. @option{-Os} enables all @option{-O2} optimizations @@ -12821,17 +13051,19 @@ It turns off @option{-fsemantic-interposition}. @opindex Og @item -Og -Optimize debugging experience. @option{-Og} should be the optimization +Optimize while keeping in mind debugging experience. +@option{-Og} should be the optimization level of choice for the standard edit-compile-debug cycle, offering -a reasonable level of optimization while maintaining fast compilation -and a good debugging experience. It is a better choice than @option{-O0} -for producing debuggable code because some compiler passes -that collect debug information are disabled at @option{-O0}. +a reasonable blend of optimization, fast compilation and debugging experience +especially for code with a high abstraction penalty. In contrast to +@option{-O0}, this enables @option{-fvar-tracking-assignments} and +@option{-fvar-tracking} which handle debug information in the prologue +and epilogue of functions better than @option{-O0}. -Like @option{-O0}, @option{-Og} completely disables a number of +Like @option{-O0}, @option{-Og} completely skips a number of optimization passes so that individual options controlling them have no effect. Otherwise @option{-Og} enables all @option{-O1} -optimization flags except for those that may interfere with debugging: +optimization flags except for those known to greatly interfere with debugging: @gccoptlist{-fbranch-count-reg -fdelayed-branch -fdse -fif-conversion -fif-conversion2 @@ -13813,6 +14045,21 @@ Enabled by default at @option{-O1} and higher. Discover read-only, write-only and non-addressable static variables. Enabled by default at @option{-O1} and higher. +@opindex fipa-reorder-for-locality +@item -fipa-reorder-for-locality +Group call chains close together in the binary layout to improve code +locality and minimize jump distances between frequently called functions. +Unlike @option{-freorder-functions} this pass considers the call +chains between functions and groups them together, rather than grouping all +hot/normal/cold/never-executed functions into separate sections. +Unlike @option{-fprofile-reorder-functions} it aims to improve code locality +throughout the runtime of the program rather than focusing on program startup. +This option is incompatible with an explicit +@option{-flto-partition=} option since it enforces a custom partitioning +scheme. +If using this option it is recommended to also use profile feedback, but this +option is not enabled by default otherwise. + @opindex fipa-stack-alignment @item -fipa-stack-alignment Reduce stack alignment on call sites if possible. @@ -14021,6 +14268,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 @@ -14227,6 +14480,7 @@ Enabled by default at @option{-O1} and higher. @item -fivopts Perform induction variable optimizations (strength reduction, induction variable merging and induction variable elimination) on trees. +Enabled by default at @option{-O1} and higher. @opindex ftree-parallelize-loops @item -ftree-parallelize-loops=n @@ -14542,11 +14796,13 @@ Enabled for x86 at levels @option{-O2}, @option{-O3}, @option{-Os}. @opindex freorder-functions @item -freorder-functions Reorder functions in the object file in order to -improve code locality. This is implemented by using special -subsections @code{.text.hot} for most frequently executed functions and -@code{.text.unlikely} for unlikely executed functions. Reordering is done by -the linker so object file format must support named sections and linker must -place them in a reasonable way. +improve code locality. Unlike @option{-fipa-reorder-for-locality} this option +prioritises grouping all functions within a category +(hot/normal/cold/never-executed) together. +This is implemented by using special subsections @code{.text.hot} for most +frequently executed functions and @code{.text.unlikely} for unlikely executed +functions. Reordering is done by the linker so object file format must support +named sections and linker must place them in a reasonable way. This option isn't effective unless you either provide profile feedback (see @option{-fprofile-arcs} for details) or manually annotate functions with @@ -14558,12 +14814,14 @@ Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. @item -fstrict-aliasing Allow the compiler to assume the strictest aliasing rules applicable to the language being compiled. For C (and C++), this activates -optimizations based on the type of expressions. In particular, an -object of one type is assumed never to reside at the same address as an -object of a different type, unless the types are almost the same. For -example, an @code{unsigned int} can alias an @code{int}, but not a -@code{void*} or a @code{double}. A character type may alias any other -type. +optimizations based on the type of expressions. In particular, accessing +an object of one type via an expression of a different type is not allowed, +unless the types are @dfn{compatible types}, differ only in signedness or +qualifiers, or the expression has a character type. Accessing scalar +objects via a corresponding vector type is also allowed. + +For example, an @code{unsigned int} can alias an @code{int}, but not a +@code{void*} or a @code{double}. A character type may alias any other type. @anchor{Type-punning}Pay special attention to code like this: @smallexample @@ -15260,6 +15518,12 @@ E.g. create_gcov --binary=your_program.unstripped --profile=perf.data \ --gcov=profile.afdo @end smallexample + +@opindex fauto-profile-inlining +@item -fauto-profile-inlining +When auto-profile is available inline all relevant functions which was +inlined in the tran run before reading the profile feedback. This improves +context sensitivity of the profile. Enabled by default. @end table The following options control compiler behavior regarding floating-point @@ -15267,32 +15531,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 +15566,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 +15712,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 @@ -15507,8 +15774,7 @@ When enabled, this option states that a range reduction step is not needed when performing complex division. Also, there is no checking whether the result of a complex multiplication or division is @code{NaN + I*NaN}, with an attempt to rescue the situation in that case. The -default is @option{-fno-cx-limited-range}, but is enabled by -@option{-ffast-math}. +option is enabled by @option{-ffast-math}. This option controls the default setting of the ISO C99 @code{CX_LIMITED_RANGE} pragma. Nevertheless, the option applies to @@ -15521,7 +15787,14 @@ reduction is done as part of complex division, but there is no checking whether the result of a complex multiplication or division is @code{NaN + I*NaN}, with an attempt to rescue the situation in that case. -The default is @option{-fno-cx-fortran-rules}. +@opindex fcx-method +@item -fcx-method=@var{method} +Complex multiplication and division follow the stated @var{method}. The +@var{method} argument should be one of @samp{limited-range}, @samp{fortran} +or @samp{stdc}. + +The default is to honor language specific constraints which means +@samp{fortran} for Fortran and @samp{stdc} otherwise. @end table @@ -15568,7 +15841,8 @@ Enabled by @option{-fprofile-generate}, @option{-fprofile-use}, and @item -fprofile-reorder-functions Function reordering based on profile instrumentation collects first time of execution of a function and orders these functions -in ascending order. +in ascending order, aiming to optimize program startup through more +efficient loading of text segments. Enabled with @option{-fprofile-use}. @@ -16466,6 +16740,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 @@ -16791,11 +17074,6 @@ Maximum depth of recursive cloning for self-recursive function. Recursive cloning only when the probability of call being executed exceeds the parameter. -@item ipa-cp-profile-count-base -When using @option{-fprofile-use} option, IPA-CP will consider the measured -execution count of a call graph edge at this percentage position in their -histogram as the basis for its heuristics calculation. - @item ipa-cp-recursive-freq-factor The number of times interprocedural copy propagation expects recursive functions to call themselves. @@ -16857,6 +17135,19 @@ Size of max partition for WHOPR (in estimated instructions). to provide an upper bound for individual size of partition. Meant to be used only with balanced partitioning. +@item lto-partition-locality-frequency-cutoff +The denominator n of fraction 1/n of the execution frequency of callee to be +cloned for a particular caller. Special value of 0 dictates to always clone +without a cut-off. + +@item lto-partition-locality-size-cutoff +Size cut-off for callee including inlined calls to be cloned for a particular +caller. + +@item lto-max-locality-partition +Maximal size of a locality partition for LTO (in estimated instructions). +Value of 0 results in default value being used. + @item lto-max-streaming-parallelism Maximal number of parallel processes used for LTO streaming. @@ -17111,8 +17402,9 @@ this parameter. The default value of this parameter is 50. @item vect-induction-float Enable loop vectorization of floating point inductions. -@item vect-force-slp -Force the use of SLP when vectorizing, fail if not possible. +@item vect-scalar-cost-multiplier +Apply the given multiplier % to scalar loop costing during vectorization. +Increasing the cost multiplier will make vector loops more profitable. @item vrp-block-limit Maximum number of basic blocks before VRP switches to a lower memory algorithm. @@ -17191,6 +17483,9 @@ predicate chain. @item uninit-max-num-chains Maximum number of predicates ored in the normalized predicate chain. +@item uninit-max-prune-work +Maximum amount of work done to prune paths where the variable is always initialized. + @item sched-autopref-queue-depth Hardware autoprefetcher scheduler model control flag. Number of lookahead cycles the model looks into; at ' @@ -17354,20 +17649,9 @@ The precision of division is proportional to this param when division approximation is enabled. The default value is 2. @item aarch64-autovec-preference -Force an ISA selection strategy for auto-vectorization. -@table @samp -@item default -Use the default heuristics. -@item asimd-only -Use only Advanced SIMD for auto-vectorization. -@item sve-only -Use only SVE for auto-vectorization. -@item prefer-asimd -Use both Advanced SIMD and SVE. Prefer Advanced SIMD when the costs are -deemed equal. -@item prefer-sve -Use both Advanced SIMD and SVE. Prefer SVE when the costs are deemed equal. -@end table +An old alias for @option{-mautovec-preference}. If both +@option{-mautovec-preference} and @option{--param=aarch64-autovec-preference} +are passed, the @option{--param} value will be used. @item aarch64-ldp-policy Fine-grained policy for load pairs. @@ -18321,7 +18605,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 +18614,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 @@ -20622,6 +20915,93 @@ By default, the dump will contain messages about successful optimizations (equivalent to @option{-optimized}) together with low-level details about the analysis. +@opindex fdump-ipa-clones +@item -fdump-ipa-clones + +Create a dump file containing information about creation of call graph +node clones and removals of call graph nodes during inter-procedural +optimizations and transformations. Its main intended use is that tools +that create live-patches can determine the set of functions that need to +be live-patched to completely replace a particular function (see +@option{-flive-patching}). The file name is generated by appending +suffix @code{ipa-clones} to the source file name, and the file is +created in the same directory as the output file. Each entry in the +file is on a separate line containing semicolon separated fields. + +In the case of call graph clone creation, the individual fields are: + +@enumerate +@item +String @code{Callgraph clone}. + +@item +Name of the function being cloned as it is presented to the assembler. + +@item +A number that uniquely represents the function being cloned in the call +graph. Note that the number is unique only within a compilation unit or +within whole-program analysis but is likely to be different in the two +phases. + +@item +The file name of the source file where the function is defined. + +@item +The line on which the function definition is located. + +@item +The column where the function definition is located. + +@item +Name of the new function clone as it is presented to the assembler. + +@item +A number that uniquely represents the new function clone in the call +graph. Note that the number is unique only within a compilation unit or +within whole-program analysis but is likely to be different in the two +phases. + +@item +The file name of the source file where the source code location of the +new clone points to. + +@item +The line to which the source code location of the new clone points to. + +@item +The column to which the source code location of the new clone points to. + +@item +A string that determines the reason for cloning. + +@end enumerate + +In the case of call graph clone removal, the individual fields are: + +@enumerate +@item +String @code{Callgraph removal}. + +@item +Name of the function being removed as it would be presented to the assembler. + +@item +A number that uniquely represents the function being cloned in the call +graph. Note that the number is unique only within a compilation unit or +within whole-program analysis but is likely to be different in the two +phases. + +@item +The file name of the source file where the function is defined. + +@item +The line on which the function definition is located. + +@item +The column where the function definition is located. + +@end enumerate + @opindex fdump-lang @item -fdump-lang Dump language-specific information. The file name is made by appending @@ -20635,30 +21015,10 @@ Dump language-specific information. The file name is made by appending @itemx -fdump-lang-@var{switch}-@var{options}=@var{filename} Control the dumping of language-specific information. The @var{options} and @var{filename} portions behave as described in the -@option{-fdump-tree} option. The following @var{switch} values are -accepted: - -@table @samp -@item all - -Enable all language-specific dumps. - -@item class -Dump class hierarchy information. Virtual table information is emitted -unless '@option{slim}' is specified. This option is applicable to C++ only. - -@item module -Dump module information. Options @option{lineno} (locations), -@option{graph} (reachability), @option{blocks} (clusters), -@option{uid} (serialization), @option{alias} (mergeable), -@option{asmname} (Elrond), @option{eh} (mapper) & @option{vops} -(macros) may provide additional information. This option is -applicable to C++ only. - -@item raw -Dump the raw internal tree data. This option is applicable to C++ only. - -@end table +@option{-fdump-tree} option. @option{-fdump-tree-all} enables all +language-specific dumps; other options vary with the language. For +instance, see @xref{C++ Dialect Options} for the @option{-fdump-lang} +flags supported by the C++ front-end. @opindex fdump-passes @item -fdump-passes @@ -21199,8 +21559,13 @@ Toggle @option{-fvar-tracking-assignments}, in the same way that @opindex Q @item -Q -Makes the compiler print out each function name as it is compiled, and -print some statistics about each pass when it finishes. +When used on the command line prior to @option{--help=}, @option{-Q} +acts as a modifier to the help output. @xref{Overall Options}, +for details about @option{--help=}. + +Otherwise, this option makes the compiler print out each function name +as it is compiled, and print some statistics about each pass when it +finishes. @opindex ftime-report @item -ftime-report @@ -21720,6 +22085,36 @@ used directly. The same applies when using @option{-mcpu=} when the selected cpu supports the @samp{lse} feature. This option is on by default. +@item -mmax-vectorization +@itemx -mno-max-vectorization +Enable or disable an override to vectorizer cost model making vectorization +always appear profitable. This option can be combined with +@option{-mautovec-preference} allowing precise control over which ISA will be +used for auto-vectorization. Unlike @option{-fno-vect-cost-model} or +@option{-fvect-cost-model=unlimited} this option does not turn off cost +comparison between different vector modes. + +@item -mautovec-preference=@var{name} +Force an ISA selection strategy for auto-vectorization. The possible +values of @var{name} are: +@table @samp +@item default +Use the default heuristics. +@item asimd-only +Use only Advanced SIMD for auto-vectorization. +@item sve-only +Use only SVE for auto-vectorization. +@item prefer-asimd +Use both Advanced SIMD and SVE. Prefer Advanced SIMD when the costs are +deemed equal. +@item prefer-sve +Use both Advanced SIMD and SVE. Prefer SVE when the costs are deemed equal. +@end table + +For best performance it is highly recommended to use @option{-mcpu} or +@option{-mtune} instead. This parameter should only be used for code +exploration. + @opindex march @item -march=@var{name} Specify the name of the target architecture and, optionally, one or @@ -21800,11 +22195,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}, @samp{gb10} specify that GCC should tune for a big.LITTLE system. The value @samp{neoverse-512tvb} specifies that GCC should tune @@ -22093,8 +22490,12 @@ Enable the FlagM2 flag conversion instructions. Enable the Pointer Authentication Extension. @item cssc Enable the Common Short Sequence Compression instructions. +@item cmpbr +Enable the shorter compare and branch instructions, @code{cbb}, @code{cbh} and +@code{cb}. @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. @@ -22374,10 +22775,20 @@ Compile for CDNA2 Instinct MI200 series devices (gfx90a). @item gfx90c Compile for GCN5 Vega 7 devices (gfx90c). +@item gfx942 +Compile for CDNA3 Instinct MI300 series devices (gfx942). (Experimental) + +@item gfx950 +Compile for the CDNA3 gfx950 devices. (Experimental) + @item gfx9-generic Compile generic code for Vega devices, executable on the following subset of GFX9 devices: gfx900, gfx902, gfx904, gfx906, gfx909 and gfx90c. (Experimental) +@item gfx9-4-generic +Compile generic code for CDNA3 devices, executable on the following subset of +GFX9 devices: gfx942 and gfx950. (Experimental) + @item gfx1030 Compile for RDNA2 gfx1030 devices (GFX10 series). @@ -23257,7 +23668,7 @@ These @samp{-m} options are defined for the ARM port: @opindex mabi @item -mabi=@var{name} Generate code for the specified ABI@. Permissible values are: @samp{apcs-gnu}, -@samp{atpcs}, @samp{aapcs}, @samp{aapcs-linux} and @samp{iwmmxt}. +@samp{atpcs}, @samp{aapcs} and @samp{aapcs-linux}. @opindex mapcs-frame @item -mapcs-frame @@ -26302,6 +26713,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 +28429,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 +28438,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 +28457,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 @@ -30417,6 +30846,7 @@ Generate code for the specified PTX ISA target architecture. Valid architecture strings are @samp{sm_30}, @samp{sm_35}, @samp{sm_37}, @samp{sm_52}, @samp{sm_53}, +@samp{sm_61}, @samp{sm_70}, @samp{sm_75}, @samp{sm_80}, and @samp{sm_89}. The default depends on how the compiler has been configured, see @@ -30443,6 +30873,7 @@ Generate code for the specified PTX ISA version. Valid version strings are @samp{3.1}, @samp{4.1}, @samp{4.2}, +@samp{5.0}, @samp{6.0}, @samp{6.3}, @samp{7.0}, @samp{7.3}, and @samp{7.8}. The default PTX ISA version is the one that added support for the @@ -30596,12 +31027,13 @@ to store the immediate to a register first. @opindex mcmodel= @opindex mcmodel=small @item -mcmodel=small -Generate OpenRISC code for the small model: The GOT is limited to 64k. This is -the default model. +Generate OpenRISC code for the small model: The GOT is limited to 64k and +function call jumps are limited to 64M offsets. This is the default model. @opindex mcmodel=large @item -mcmodel=large -Generate OpenRISC code for the large model: The GOT may grow up to 4G in size. +Generate OpenRISC code for the large model: The GOT may grow up to 4G in size +and function call jumps can target the full 4G address space. @end table @@ -30834,11 +31266,16 @@ The default is @option{-misa-spec=20191213} unless GCC has been configured with @option{--with-isa-spec=} specifying a different default version. @opindex march -@item -march=@var{ISA-string} -Generate code for given RISC-V ISA (e.g.@: @samp{rv64im}). ISA strings must be -lower-case. Examples include @samp{rv64i}, @samp{rv32g}, @samp{rv32e}, and -@samp{rv32imaf}. Additionally, a special value @option{help} -(@option{-march=help}) is accepted to list all supported extensions. +@item -march=@var{ISA-string|Profiles|Profile_ISA-string} +Generate code for given RISC-V ISA or Profiles or a combination of them +(e.g.@: @samp{rv64im} @samp{rvi20u64} @samp{rvi20u64_zbb}). ISA strings and +Profiles must be lower-case. Examples include @samp{rv64i}, @samp{rv32g}, +@samp{rv32e}, @samp{rv32imaf}, @samp{rva22u64} and @samp{rva23u64}. +To combine Profiles and optional RISC-V ISA extention, the profile should start +at the beginning of the option, then use underline connect ISA-string (e.g.@: +@samp{rvi20u64_zca_zcb} @samp{rva23u64_zacas}). Additionally, a special value +@option{help} (@option{-march=help}) is accepted to list all supported +extensions. The syntax of the ISA string is defined as follows: @@ -30857,493 +31294,8 @@ syntax @samp{<major>p<minor>} or @samp{<major>}, (e.g.@: @samp{m2p1} or @end table Supported extension are listed below: -@multitable @columnfractions .10 .10 .80 -@headitem Extension Name @tab Supported Version @tab Description -@item i -@tab 2.0, 2.1 -@tab Base integer extension. - -@item e -@tab 2.0 -@tab Reduced base integer extension. - -@item g -@tab - -@tab General-purpose computing base extension, @samp{g} will expand to -@samp{i}, @samp{m}, @samp{a}, @samp{f}, @samp{d}, @samp{zicsr} and -@samp{zifencei}. - -@item m -@tab 2.0 -@tab Integer multiplication and division extension. - -@item a -@tab 2.0, 2.1 -@tab Atomic extension. - -@item f -@tab 2.0, 2.2 -@tab Single-precision floating-point extension. - -@item d -@tab 2.0, 2.2 -@tab Double-precision floating-point extension. - -@item c -@tab 2.0 -@tab Compressed extension. - -@item h -@tab 1.0 -@tab Hypervisor extension. - -@item v -@tab 1.0 -@tab Vector extension. - -@item zicsr -@tab 2.0 -@tab Control and status register access extension. - -@item zifencei -@tab 2.0 -@tab Instruction-fetch fence extension. - -@item zicond -@tab 1.0 -@tab Integer conditional operations extension. - -@item za64rs -@tab 1.0 -@tab Reservation set size of 64 bytes. - -@item za128rs -@tab 1.0 -@tab Reservation set size of 128 bytes. - -@item zawrs -@tab 1.0 -@tab Wait-on-reservation-set extension. - -@item zba -@tab 1.0 -@tab Address calculation extension. - -@item zbb -@tab 1.0 -@tab Basic bit manipulation extension. - -@item zbc -@tab 1.0 -@tab Carry-less multiplication extension. - -@item zbs -@tab 1.0 -@tab Single-bit operation extension. - -@item zfinx -@tab 1.0 -@tab Single-precision floating-point in integer registers extension. - -@item zdinx -@tab 1.0 -@tab Double-precision floating-point in integer registers extension. - -@item zhinx -@tab 1.0 -@tab Half-precision floating-point in integer registers extension. - -@item zhinxmin -@tab 1.0 -@tab Minimal half-precision floating-point in integer registers extension. - -@item zbkb -@tab 1.0 -@tab Cryptography bit-manipulation extension. - -@item zbkc -@tab 1.0 -@tab Cryptography carry-less multiply extension. - -@item zbkx -@tab 1.0 -@tab Cryptography crossbar permutation extension. - -@item zkne -@tab 1.0 -@tab AES Encryption extension. - -@item zknd -@tab 1.0 -@tab AES Decryption extension. - -@item zknh -@tab 1.0 -@tab Hash function extension. - -@item zkr -@tab 1.0 -@tab Entropy source extension. - -@item zksed -@tab 1.0 -@tab SM4 block cipher extension. - -@item zksh -@tab 1.0 -@tab SM3 hash function extension. - -@item zkt -@tab 1.0 -@tab Data independent execution latency extension. - -@item zk -@tab 1.0 -@tab Standard scalar cryptography extension. - -@item zkn -@tab 1.0 -@tab NIST algorithm suite extension. - -@item zks -@tab 1.0 -@tab ShangMi algorithm suite extension. - -@item zihintntl -@tab 1.0 -@tab Non-temporal locality hints extension. - -@item zihintpause -@tab 1.0 -@tab Pause hint extension. - -@item zicboz -@tab 1.0 -@tab Cache-block zero extension. - -@item zicbom -@tab 1.0 -@tab Cache-block management extension. - -@item zicbop -@tab 1.0 -@tab Cache-block prefetch extension. - -@item zic64b -@tab 1.0 -@tab Cache block size isf 64 bytes. -@item ziccamoa -@tab 1.0 -@tab Main memory supports all atomics in A. - -@item ziccif -@tab 1.0 -@tab Main memory supports instruction fetch with atomicity requirement. - -@item zicclsm -@tab 1.0 -@tab Main memory supports misaligned loads/stores. - -@item ziccrse -@tab 1.0 -@tab Main memory supports forward progress on LR/SC sequences. - -@item zicntr -@tab 2.0 -@tab Standard extension for base counters and timers. - -@item zihpm -@tab 2.0 -@tab Standard extension for hardware performance counters. - -@item ztso -@tab 1.0 -@tab Total store ordering extension. - -@item zve32x -@tab 1.0 -@tab Vector extensions for embedded processors. - -@item zve32f -@tab 1.0 -@tab Vector extensions for embedded processors. - -@item zve64x -@tab 1.0 -@tab Vector extensions for embedded processors. - -@item zve64f -@tab 1.0 -@tab Vector extensions for embedded processors. - -@item zve64d -@tab 1.0 -@tab Vector extensions for embedded processors. - -@item zvl32b -@tab 1.0 -@tab Minimum vector length standard extensions - -@item zvl64b -@tab 1.0 -@tab Minimum vector length standard extensions - -@item zvl128b -@tab 1.0 -@tab Minimum vector length standard extensions - -@item zvl256b -@tab 1.0 -@tab Minimum vector length standard extensions - -@item zvl512b -@tab 1.0 -@tab Minimum vector length standard extensions - -@item zvl1024b -@tab 1.0 -@tab Minimum vector length standard extensions - -@item zvl2048b -@tab 1.0 -@tab Minimum vector length standard extensions - -@item zvl4096b -@tab 1.0 -@tab Minimum vector length standard extensions - -@item zvbb -@tab 1.0 -@tab Vector basic bit-manipulation extension. - -@item zvbc -@tab 1.0 -@tab Vector carryless multiplication extension. - -@item zvkb -@tab 1.0 -@tab Vector cryptography bit-manipulation extension. - -@item zvkg -@tab 1.0 -@tab Vector GCM/GMAC extension. - -@item zvkned -@tab 1.0 -@tab Vector AES block cipher extension. - -@item zvknha -@tab 1.0 -@tab Vector SHA-2 secure hash extension. - -@item zvknhb -@tab 1.0 -@tab Vector SHA-2 secure hash extension. - -@item zvksed -@tab 1.0 -@tab Vector SM4 Block Cipher extension. - -@item zvksh -@tab 1.0 -@tab Vector SM3 Secure Hash extension. - -@item zvkn -@tab 1.0 -@tab Vector NIST Algorithm Suite extension, @samp{zvkn} will expand to -@samp{zvkned}, @samp{zvknhb}, @samp{zvkb} and @samp{zvkt}. - -@item zvknc -@tab 1.0 -@tab Vector NIST Algorithm Suite with carryless multiply extension, @samp{zvknc} -will expand to @samp{zvkn} and @samp{zvbc}. - -@item zvkng -@tab 1.0 -@tab Vector NIST Algorithm Suite with GCM extension, @samp{zvkng} will expand -to @samp{zvkn} and @samp{zvkg}. - -@item zvks -@tab 1.0 -@tab Vector ShangMi algorithm suite extension, @samp{zvks} will expand -to @samp{zvksed}, @samp{zvksh}, @samp{zvkb} and @samp{zvkt}. - -@item zvksc -@tab 1.0 -@tab Vector ShangMi algorithm suite with carryless multiplication extension, -@samp{zvksc} will expand to @samp{zvks} and @samp{zvbc}. - -@item zvksg -@tab 1.0 -@tab Vector ShangMi algorithm suite with GCM extension, @samp{zvksg} will expand -to @samp{zvks} and @samp{zvkg}. - -@item zvkt -@tab 1.0 -@tab Vector data independent execution latency extension. - -@item zfh -@tab 1.0 -@tab Half-precision floating-point extension. - -@item zfhmin -@tab 1.0 -@tab Minimal half-precision floating-point extension. - -@item zvfh -@tab 1.0 -@tab Vector half-precision floating-point extension. - -@item zvfhmin -@tab 1.0 -@tab Vector minimal half-precision floating-point extension. - -@item zvfbfmin -@tab 1.0 -@tab Vector BF16 converts extension. - -@item zfa -@tab 1.0 -@tab Additional floating-point extension. - -@item zmmul -@tab 1.0 -@tab Integer multiplication extension. - -@item zca -@tab 1.0 -@tab Integer compressed instruction extension. - -@item zcf -@tab 1.0 -@tab Compressed single-precision floating point loads and stores extension. - -@item zcd -@tab 1.0 -@tab Compressed double-precision floating point loads and stores extension. - -@item zcb -@tab 1.0 -@tab Simple compressed instruction extension. - -@item zce -@tab 1.0 -@tab Compressed instruction extensions for embedded processors. - -@item zcmp -@tab 1.0 -@tab Compressed push pop extension. - -@item zcmt -@tab 1.0 -@tab Table jump instruction extension. - -@item smaia -@tab 1.0 -@tab Advanced interrupt architecture extension. - -@item smepmp -@tab 1.0 -@tab PMP Enhancements for memory access and execution prevention on Machine mode. - -@item smstateen -@tab 1.0 -@tab State enable extension. - -@item ssaia -@tab 1.0 -@tab Advanced interrupt architecture extension for supervisor-mode. - -@item sscofpmf -@tab 1.0 -@tab Count overflow & filtering extension. - -@item ssstateen -@tab 1.0 -@tab State-enable extension for supervisor-mode. - -@item sstc -@tab 1.0 -@tab Supervisor-mode timer interrupts extension. - -@item svinval -@tab 1.0 -@tab Fine-grained address-translation cache invalidation extension. - -@item svnapot -@tab 1.0 -@tab NAPOT translation contiguity extension. - -@item svpbmt -@tab 1.0 -@tab Page-based memory types extension. - -@item xcvmac -@tab 1.0 -@tab Core-V multiply-accumulate extension. - -@item xcvalu -@tab 1.0 -@tab Core-V miscellaneous ALU extension. - -@item xcvelw -@tab 1.0 -@tab Core-V event load word extension. - -@item xtheadba -@tab 1.0 -@tab T-head address calculation extension. - -@item xtheadbb -@tab 1.0 -@tab T-head basic bit-manipulation extension. - -@item xtheadbs -@tab 1.0 -@tab T-head single-bit instructions extension. - -@item xtheadcmo -@tab 1.0 -@tab T-head cache management operations extension. - -@item xtheadcondmov -@tab 1.0 -@tab T-head conditional move extension. - -@item xtheadfmemidx -@tab 1.0 -@tab T-head indexed memory operations for floating-point registers extension. - -@item xtheadfmv -@tab 1.0 -@tab T-head double floating-point high-bit data transmission extension. - -@item xtheadint -@tab 1.0 -@tab T-head acceleration interruption extension. - -@item xtheadmac -@tab 1.0 -@tab T-head multiply-accumulate extension. - -@item xtheadmemidx -@tab 1.0 -@tab T-head indexed memory operation extension. - -@item xtheadmempair -@tab 1.0 -@tab T-head two-GPR memory operation extension. - -@item xtheadsync -@tab 1.0 -@tab T-head multi-core synchronization extension. - -@item xventanacondops -@tab 1.0 -@tab Ventana integer conditional operations extension. - -@end multitable +@include riscv-ext.texi When @option{-march=} is not specified, use the setting from @option{-mcpu}. @@ -31359,12 +31311,13 @@ extension set if they weren't added explicitly. @item -mcpu=@var{processor-string} Use architecture of and optimize the output for the given processor, specified by particular CPU name. -Permissible values for this option are: @samp{sifive-e20}, @samp{sifive-e21}, -@samp{sifive-e24}, @samp{sifive-e31}, @samp{sifive-e34}, @samp{sifive-e76}, -@samp{sifive-s21}, @samp{sifive-s51}, @samp{sifive-s54}, @samp{sifive-s76}, -@samp{sifive-u54}, @samp{sifive-u74}, @samp{sifive-x280}, @samp{sifive-xp450}, -@samp{sifive-x670}, @samp{thead-c906}, @samp{tt-ascalon-d8}, -@samp{xiangshan-nanhu}. +Permissible values for this option are: @samp{mips-p8700}, @samp{sifive-e20}, +@samp{sifive-e21}, @samp{sifive-e24}, @samp{sifive-e31}, @samp{sifive-e34}, +@samp{sifive-e76}, @samp{sifive-s21}, @samp{sifive-s51}, @samp{sifive-s54}, +@samp{sifive-s76}, @samp{sifive-u54}, @samp{sifive-u74}, @samp{sifive-x280}, +@samp{sifive-xp450}, @samp{sifive-x670}, @samp{thead-c906}, @samp{tt-ascalon-d8}, +@samp{xiangshan-nanhu}, @samp{xiangshan-kunminghu}, @samp{xt-c908}, @samp{xt-c908v}, +@samp{xt-c910}, @samp{xt-c910v2}, @samp{xt-c920}, @samp{xt-c920v2}. Note that @option{-mcpu} does not override @option{-march} or @option{-mtune}. @@ -31372,7 +31325,7 @@ Note that @option{-mcpu} does not override @option{-march} or @option{-mtune}. @item -mtune=@var{processor-string} Optimize the output for the given processor, specified by microarchitecture or particular CPU name. Permissible values for this option are: -@samp{generic-ooo}, @samp{rocket}, @samp{sifive-3-series}, +@samp{generic-ooo}, @samp{mips-p8700}, @samp{rocket}, @samp{sifive-3-series}, @samp{sifive-5-series}, @samp{sifive-7-series}, @samp{size}, @samp{sifive-p400-series}, @samp{sifive-p600-series}, and all valid options for @option{-mcpu=}. @@ -32372,18 +32325,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 @@ -33238,7 +33191,7 @@ system representing a certain processor type. Possible values for @samp{z9-109}, @samp{z9-ec}/@samp{arch7}, @samp{z10}/@samp{arch8}, @samp{z196}/@samp{arch9}, @samp{zEC12}, @samp{z13}/@samp{arch11}, @samp{z14}/@samp{arch12}, @samp{z15}/@samp{arch13}, -@samp{z16}/@samp{arch14}, and @samp{native}. +@samp{z16}/@samp{arch14}, @samp{z17}/@samp{arch15}, and @samp{native}. The default is @option{-march=z900}. @@ -34732,7 +34685,8 @@ produces code optimized for the local machine under the constraints of the selected instruction set. @item x86-64 -A generic CPU with 64-bit extensions. +A generic CPU with 64-bit extensions, MMX, SSE, SSE2, and FXSR instruction set +support. @item x86-64-v2 @itemx x86-64-v3 @@ -34765,7 +34719,7 @@ Intel Lakemont MCU, based on Intel Pentium CPU. Intel Pentium MMX CPU, based on Pentium core with MMX instruction set support. @item pentiumpro -Intel Pentium Pro CPU@. +Intel Pentium Pro CPU with no MMX support. @item i686 When used with @option{-march}, the Pentium Pro @@ -34911,37 +34865,36 @@ VPCLMULQDQ, AVX512BITALG, RDPID and AVX512VPOPCNTDQ instruction set support. Intel Alder Lake/Raptor Lake/Meteor Lake/Gracemont CPU with 64-bit extensions, MOVBE, MMX, SSE, SSE2, SSE3, SSSE3, SSE4.1, SSE4.2, POPCNT, AES, PREFETCHW, PCLMUL, RDRND, XSAVE, XSAVEC, XSAVES, XSAVEOPT, FSGSBASE, PTWRITE, RDPID, SGX, -GFNI-SSE, CLWB, MOVDIRI, MOVDIR64B, CLDEMOTE, WAITPKG, ADCX, AVX, AVX2, BMI, -BMI2, F16C, FMA, LZCNT, PCONFIG, PKU, VAES, VPCLMULQDQ, SERIALIZE, HRESET, KL, -WIDEKL and AVX-VNNI instruction set support. +GFNI-SSE, CLWB, MOVDIRI, MOVDIR64B, WAITPKG, ADCX, AVX, AVX2, BMI, BMI2, F16C, +FMA, LZCNT, PCONFIG, PKU, VAES, VPCLMULQDQ, SERIALIZE, HRESET, KL, WIDEKL and +AVX-VNNI instruction set support. @item arrowlake Intel Arrow Lake CPU with 64-bit extensions, MOVBE, MMX, SSE, SSE2, SSE3, SSSE3, SSE4.1, SSE4.2, POPCNT, AES, PREFETCHW, PCLMUL, RDRND, XSAVE, XSAVEC, XSAVES, XSAVEOPT, FSGSBASE, PTWRITE, RDPID, SGX, GFNI-SSE, CLWB, MOVDIRI, -MOVDIR64B, CLDEMOTE, WAITPKG, ADCX, AVX, AVX2, BMI, BMI2, F16C, FMA, LZCNT, -PCONFIG, PKU, VAES, VPCLMULQDQ, SERIALIZE, HRESET, KL, WIDEKL, AVX-VNNI, -UINTR, AVXIFMA, AVXVNNIINT8, AVXNECONVERT and CMPCCXADD instruction set -support. +MOVDIR64B, WAITPKG, ADCX, AVX, AVX2, BMI, BMI2, F16C, FMA, LZCNT, PCONFIG, PKU, +VAES, VPCLMULQDQ, SERIALIZE, HRESET, KL, WIDEKL, AVX-VNNI, UINTR, AVXIFMA, +AVXVNNIINT8, AVXNECONVERT and CMPCCXADD instruction set support. @item arrowlake-s @itemx lunarlake Intel Arrow Lake S/Lunar Lake CPU with 64-bit extensions, MOVBE, MMX, SSE, SSE2, SSE3, SSSE3, SSE4.1, SSE4.2, POPCNT, AES, PREFETCHW, PCLMUL, RDRND, XSAVE, XSAVEC, XSAVES, XSAVEOPT, FSGSBASE, PTWRITE, RDPID, SGX, GFNI-SSE, CLWB, -MOVDIRI, MOVDIR64B, CLDEMOTE, WAITPKG, ADCX, AVX, AVX2, BMI, BMI2, F16C, FMA, -LZCNT, PCONFIG, PKU, VAES, VPCLMULQDQ, SERIALIZE, HRESET, KL, WIDEKL, AVX-VNNI, -UINTR, AVXIFMA, AVXVNNIINT8, AVXNECONVERT, CMPCCXADD, AVXVNNIINT16, SHA512, -SM3 and SM4 instruction set support. +MOVDIRI, MOVDIR64B, WAITPKG, ADCX, AVX, AVX2, BMI, BMI2, F16C, FMA, LZCNT, +PCONFIG, PKU, VAES, VPCLMULQDQ, SERIALIZE, HRESET, KL, WIDEKL, AVX-VNNI, UINTR, +AVXIFMA, AVXVNNIINT8, AVXNECONVERT, CMPCCXADD, AVXVNNIINT16, SHA512, SM3 and +SM4 instruction set support. @item pantherlake Intel Panther Lake CPU with 64-bit extensions, MOVBE, MMX, SSE, SSE2, SSE3, SSSE3, SSE4.1, SSE4.2, POPCNT, AES, PREFETCHW, PCLMUL, RDRND, XSAVE, XSAVEC, XSAVES, XSAVEOPT, FSGSBASE, PTWRITE, RDPID, SGX, GFNI-SSE, CLWB, MOVDIRI, -MOVDIR64B, CLDEMOTE, WAITPKG, ADCX, AVX, AVX2, BMI, BMI2, F16C, FMA, LZCNT, -PCONFIG, PKU, VAES, VPCLMULQDQ, SERIALIZE, HRESET, KL, WIDEKL, AVX-VNNI, -UINTR, AVXIFMA, AVXVNNIINT8, AVXNECONVERT, CMPCCXADD, AVXVNNIINT16, SHA512, -SM3, SM4 and PREFETCHI instruction set support. +MOVDIR64B, WAITPKG, ADCX, AVX, AVX2, BMI, BMI2, F16C, FMA, LZCNT, PCONFIG, PKU, +VAES, VPCLMULQDQ, SERIALIZE, HRESET, KL, WIDEKL, AVX-VNNI, UINTR, AVXIFMA, +AVXVNNIINT8, AVXNECONVERT, CMPCCXADD, AVXVNNIINT16, SHA512, SM3, SM4 and +PREFETCHI instruction set support. @item sapphirerapids @itemx emeraldrapids @@ -35293,8 +35246,8 @@ Produce code optimized for the most current Intel processors, which are Haswell and Silvermont for this version of GCC. If you know the CPU on which your code will run, then you should use the corresponding @option{-mtune} or @option{-march} option instead of @option{-mtune=intel}. -But, if you want your application performs better on both Haswell and -Silvermont, then you should use this option. +But, if you want your application performs better on both Diamond Rapids +and Clearwater Forest, then you should use this option. As new Intel processors are deployed in the marketplace, the behavior of this option will change. Therefore, if you upgrade to a newer version of @@ -35936,12 +35889,6 @@ preferred alignment to @option{-mpreferred-stack-boundary=2}. @opindex mavx10.1 @itemx -mavx10.1 @need 200 -@opindex mavx10.1-256 -@itemx -mavx10.1-256 -@need 200 -@opindex mavx10.1-512 -@itemx -mavx10.1-512 -@need 200 @opindex mavx10.2 @itemx -mavx10.2 @need 200 @@ -36730,11 +36677,6 @@ To invoke egpr usage in inline asm, use new compiler option -mapx-inline-asm-use-gpr32 and user should ensure the instruction supports EGPR. -@opindex mevex512 -@item -mevex512 -@itemx -mno-evex512 -Enables/disables 512-bit vector. It will be default on if AVX512F is enabled. - @end table These @samp{-m} switches are supported in addition to the above diff --git a/gcc/doc/libgdiagnostics/topics/compatibility.rst b/gcc/doc/libgdiagnostics/topics/compatibility.rst new file mode 100644 index 0000000..0e078d0 --- /dev/null +++ b/gcc/doc/libgdiagnostics/topics/compatibility.rst @@ -0,0 +1,221 @@ +.. Copyright (C) 2015-2025 Free Software Foundation, Inc. + Originally contributed by David Malcolm <dmalcolm@redhat.com> + + This is free software: you can redistribute it and/or modify it + under the terms of the GNU General Public License as published by + the Free Software Foundation, either version 3 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see + <https://www.gnu.org/licenses/>. + +.. default-domain:: c + +ABI and API compatibility +========================= + +The libgdiagnostics developers strive for ABI and API backward-compatibility: +programs built against libgdiagnostics.so stand a good chance of running +without recompilation against newer versions of libgdiagnostics.so, and +ought to recompile without modification against newer versions of +libgdiagnostics.h. + +.. note:: The libgdiagnostics++.h C++ API is more experimental, and less + locked-down at this time. + +API compatibility is achieved by extending the API rather than changing +it. For ABI compatiblity, we avoid bumping the SONAME, and instead use +symbol versioning to tag each symbol, so that a binary linked against +libgdiagnostics.so is tagged according to the symbols that it uses. + +For example, :func:`diagnostic_logical_location_get_kind` was added in +``LIBGDIAGNOSTICS_ABI_1``. If a client program uses it, this can be detected +from metadata by using ``objdump``: + +.. code-block:: bash + + $ objdump -p testsuite/libgdiagnostics/test-logical-location.c.exe | tail -n 7 + + Version References: + required from libc.so.6: + 0x09691a75 0x00 04 GLIBC_2.2.5 + required from libgdiagnostics.so.0: + 0x0ec567d1 0x00 03 LIBGDIAGNOSTICS_ABI_1 + 0x0ec567d0 0x00 02 LIBGDIAGNOSTICS_ABI_0 + +You can see the symbol tags provided by libgdiagnostics.so using ``objdump``: + +.. code-block:: bash + + $ objdump -p libgdiagnostics.so | less + [...snip...] + Version definitions: + 1 0x01 0x099ea4b0 libgdiagnostics.so.0 + 2 0x00 0x0ec567d0 LIBGDIAGNOSTICS_ABI_0 + 3 0x00 0x0ec567d1 LIBGDIAGNOSTICS_ABI_1 + LIBGDIAGNOSTICS_ABI_0 + [...snip...] + +ABI symbol tags +*************** + +.. _LIBGDIAGNOSTICS_ABI_0: + +``LIBGDIAGNOSTICS_ABI_0`` +------------------------- + +All entrypoints in the initial release of libgdiagnostics (in GCC 15) are +tagged with ``LIBGDIAGNOSTICS_ABI_0``; these entrypoints are: + + * :func:`diagnostic_manager_new` + + * :func:`diagnostic_manager_release` + + * :func:`diagnostic_manager_set_tool_name` + + * :func:`diagnostic_manager_set_full_name` + + * :func:`diagnostic_manager_set_version_string` + + * :func:`diagnostic_manager_set_version_url` + + * :func:`diagnostic_manager_add_text_sink` + + * :func:`diagnostic_text_sink_set_source_printing_enabled` + + * :func:`diagnostic_text_sink_set_colorize` + + * :func:`diagnostic_text_sink_set_labelled_source_colorization_enabled` + + * :func:`diagnostic_manager_add_sarif_sink` + + * :func:`diagnostic_manager_write_patch` + + * :func:`diagnostic_manager_new_file` + + * :func:`diagnostic_file_set_buffered_content` + + * :func:`diagnostic_manager_debug_dump_file` + + * :func:`diagnostic_manager_new_location_from_file_and_line` + + * :func:`diagnostic_manager_new_location_from_file_line_column` + + * :func:`diagnostic_manager_new_location_from_range` + + * :func:`diagnostic_manager_debug_dump_location` + + * :func:`diagnostic_manager_new_logical_location` + + * :func:`diagnostic_manager_debug_dump_logical_location` + + * :func:`diagnostic_manager_begin_group` + + * :func:`diagnostic_manager_end_group` + + * :func:`diagnostic_begin` + + * :func:`diagnostic_set_cwe` + + * :func:`diagnostic_add_rule` + + * :func:`diagnostic_set_location` + + * :func:`diagnostic_set_location_with_label` + + * :func:`diagnostic_add_location` + + * :func:`diagnostic_add_location_with_label` + + * :func:`diagnostic_set_logical_location` + + * :func:`diagnostic_add_fix_it_hint_insert_before` + + * :func:`diagnostic_add_fix_it_hint_insert_after` + + * :func:`diagnostic_add_fix_it_hint_replace` + + * :func:`diagnostic_add_fix_it_hint_delete` + + * :func:`diagnostic_add_execution_path` + + * :func:`diagnostic_manager_new_execution_path` + + * :func:`diagnostic_take_execution_path` + + * :func:`diagnostic_execution_path_release` + + * :func:`diagnostic_execution_path_add_event` + + * :func:`diagnostic_execution_path_add_event_va` + + * :func:`diagnostic_finish` + + * :func:`diagnostic_finish_va` + + * :func:`diagnostic_physical_location_get_file` + +.. _LIBGDIAGNOSTICS_ABI_1: + +``LIBGDIAGNOSTICS_ABI_1`` +------------------------- +``LIBGDIAGNOSTICS_ABI_1`` covers the addition of these functions for +acccessing values within a :type:`diagnostic_logical_location`: + + * :func:`diagnostic_logical_location_get_kind` + + * :func:`diagnostic_logical_location_get_parent` + + * :func:`diagnostic_logical_location_get_short_name` + + * :func:`diagnostic_logical_location_get_fully_qualified_name` + + * :func:`diagnostic_logical_location_get_decorated_name` + +.. _LIBGDIAGNOSTICS_ABI_2: + +``LIBGDIAGNOSTICS_ABI_2`` +------------------------- +``LIBGDIAGNOSTICS_ABI_2`` covers the addition of these functions for +supporting command-line options and SARIF playback: + + * :func:`diagnostic_manager_add_sink_from_spec` + + * :func:`diagnostic_manager_set_analysis_target` + +.. _LIBGDIAGNOSTICS_ABI_3: + +``LIBGDIAGNOSTICS_ABI_3`` +------------------------- +``LIBGDIAGNOSTICS_ABI_3`` covers the addition of these functions for +working with directed graphs: + + * :func:`diagnostic_manager_new_graph` + + * :func:`diagnostic_manager_take_global_graph` + + * :func:`diagnostic_take_graph` + + * :func:`diagnostic_graph_release` + + * :func:`diagnostic_graph_set_description` + + * :func:`diagnostic_graph_add_node` + + * :func:`diagnostic_graph_add_edge` + + * :func:`diagnostic_graph_get_node_by_id` + + * :func:`diagnostic_graph_get_edge_by_id` + + * :func:`diagnostic_node_set_label` + + * :func:`diagnostic_node_set_location` + + * :func:`diagnostic_node_set_logical_location` diff --git a/gcc/doc/libgdiagnostics/topics/diagnostic-manager.rst b/gcc/doc/libgdiagnostics/topics/diagnostic-manager.rst index d594b260..c94d19e 100644 --- a/gcc/doc/libgdiagnostics/topics/diagnostic-manager.rst +++ b/gcc/doc/libgdiagnostics/topics/diagnostic-manager.rst @@ -56,3 +56,45 @@ Responsibilities include: This will flush output to all of the output sinks, and clean up. The parameter must be non-NULL. + +.. function:: int diagnostic_manager_add_sink_from_spec (diagnostic_manager *affected_mgr, \ + const char *option_name, \ + const char *spec, \ + diagnostic_manager *control_mgr) + + This function can be used to support option processing similar to GCC's + `-fdiagnostics-add-output= <https://gcc.gnu.org/onlinedocs/gcc/Diagnostic-Message-Formatting-Options.html#index-fdiagnostics-add-output>`_. + This allows command-line tools to support the same domain-specific + language for specifying output sinks as GCC does. + + The function will attempt to parse ``spec`` as if it were + an argument to GCC's `-fdiagnostics-add-output= <https://gcc.gnu.org/onlinedocs/gcc/Diagnostic-Message-Formatting-Options.html#index-fdiagnostics-add-output>`_. + If successful, it will add an output sink to ``affected_mgr`` and return zero. + Otherwise, it will emit an error diagnostic to ``control_mgr`` and + return non-zero. + + ``affected_mgr`` and ``control_mgr`` can be the same manager, + or be different managers. + + This function was added in :ref:`LIBGDIAGNOSTICS_ABI_2`; you can + test for its presence using + + .. code-block:: c + + #ifdef LIBDIAGNOSTICS_HAVE_diagnostic_manager_add_sink_from_spec + +.. function:: void diagnostic_manager_set_analysis_target (diagnostic_manager *mgr, \ + const diagnostic_file *file) + + This function sets the "main input file" of ``mgr`` to be + ``file``. + This affects the :code:`<title>` of generated HTML and + the :code:`role` of the :code:`artifact` in SARIF output + (`SARIF v2.1.0 section 3.24.6 <https://docs.oasis-open.org/sarif/sarif/v2.1.0/errata01/os/sarif-v2.1.0-errata01-os-complete.html#_Toc141790867>`_). + + This function was added in :ref:`LIBGDIAGNOSTICS_ABI_2`; you can + test for its presence using + + .. code-block:: c + + #ifdef LIBDIAGNOSTICS_HAVE_diagnostic_manager_set_analysis_target diff --git a/gcc/doc/libgdiagnostics/topics/graphs.rst b/gcc/doc/libgdiagnostics/topics/graphs.rst new file mode 100644 index 0000000..b976013 --- /dev/null +++ b/gcc/doc/libgdiagnostics/topics/graphs.rst @@ -0,0 +1,197 @@ +.. Copyright (C) 2025 Free Software Foundation, Inc. + Originally contributed by David Malcolm <dmalcolm@redhat.com> + + This is free software: you can redistribute it and/or modify it + under the terms of the GNU General Public License as published by + the Free Software Foundation, either version 3 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see + <https://www.gnu.org/licenses/>. + +.. default-domain:: c + +Graphs +====== + +.. type:: diagnostic_graph + +SARIF has support for capturing directed graphs (such as callgraphs +and control flow graphs), both at the level of the run as a whole, +and at the level of individual results. + +libgdiagnostics supports this with the following entrypoints, allowing +directed graphs to be + +* created (with :func:`diagnostic_manager_new_graph`) + +* reported "globally" (with :func:`diagnostic_manager_take_global_graph`) + +* reported as part of a :type:`diagnostic` (with :func:`diagnostic_take_graph`), or + +* discarded (with :func:`diagnostic_graph_release`). + +.. function:: diagnostic_graph * diagnostic_manager_new_graph (diagnostic_manager *manager) + + Create a new directed graph. + + The resulting graph is owned by the caller and must have one of + :func:`diagnostic_manager_take_global_graph`, + :func:`diagnostic_take_graph`, + or :func:`diagnostic_graph_release` called on it to avoid leaks. + + The parameter ``manager`` must be non-null. + + This function was added in :ref:`LIBGDIAGNOSTICS_ABI_3`. + +.. function:: void diagnostic_manager_take_global_graph (diagnostic_manager *manager, \ + diagnostic_graph *graph) + + Report this graph "globally", taking ownership of it. + This won't appear in text sinks, but in SARIF sinks the graph will be + added to theRun.graphs (SARIF v2.1.0 3.14.20). + + Parameters ``manager`` and ``graph`` must both be non-null. + + This function was added in :ref:`LIBGDIAGNOSTICS_ABI_3`. + +.. function:: void diagnostic_take_graph (diagnostic *diag, \ + diagnostic_graph *graph) + + Add this graph to ``diag``, transferring ownership of it to ``diag``. + This won't appear in text sinks, but in SARIF sinks the graph will be + added to theResult.graphs (SARIF v2.1.0 3.27.19). + + Parameters ``diag`` and ``graph`` must both be non-null. + + This function was added in :ref:`LIBGDIAGNOSTICS_ABI_3`. + +.. function:: void diagnostic_graph_release (diagnostic_graph *graph) + + Release ``graph`` which must still be owned by the caller + i.e. it must *not* have had + :func:`diagnostic_manager_take_global_graph` or + :func:`diagnostic_take_graph` called on it. + + Parameters ``graph`` can be null. + + This function was added in :ref:`LIBGDIAGNOSTICS_ABI_3`. + + +.. function:: void diagnostic_graph_set_description (diagnostic_graph *graph, \ + const char *description) + + Set the description of ``graph`` for use in the value of the + SARIF ``description`` property (SARIF v2.1.0 section 3.39.2). + + The parameter ``graph`` must be non-null. + The parameter ``description`` can be null, for clearing any existing + description. + + This function was added in :ref:`LIBGDIAGNOSTICS_ABI_3`. + +.. function:: diagnostic_node * diagnostic_graph_add_node (diagnostic_graph *graph, \ + const char *node_id, \ + diagnostic_node *parent_node) + + Create and add a new node within ``graph`` with the given `id``. + The id must be unique within nodes in ``graph``. + + The parameters ``graph`` and ``id`` must be non-null. + + ``parent_node`` can be NULL (for a top-level node in the graph), + or non-null for a child node, allowing for arbitrary nesting of + nodes. + + The new node is owned by ``graph``. + + This function was added in :ref:`LIBGDIAGNOSTICS_ABI_3`. + +.. function:: diagnostic_edge * diagnostic_graph_add_edge (diagnostic_graph *graph, \ + const char *edge_id, \ + diagnostic_node *src_node, \ + diagnostic_node *dst_node, \ + const char *label) + + Create and add a new edge within ``graph``. + + The parameters ``graph``, ``src_node`` and ``dest_node`` + must be non-null. + + If non-null, then ``edge_id`` must be unique within ``graph``; + if ``edge_id`` is null then a unique id of the form "edge0", "edge1", + etc will be used automatically. + + If non-null, then ``label`` will be used for the value of the + SARIF ``label`` property (SARIF v2.1.0 section 3.41.3). + + The new edge is owned by ``graph``. + + This function was added in :ref:`LIBGDIAGNOSTICS_ABI_3`. + +.. function:: diagnostic_node *diagnostic_graph_get_node_by_id (diagnostic_graph *graph, \ + const char *node_id) + + Get the node in ``graph`` with the given id, or null. + + The parameters ``graph`` and ``node_id`` must be non-null. + + This function was added in :ref:`LIBGDIAGNOSTICS_ABI_3`. + +.. function:: diagnostic_edge *diagnostic_graph_get_edge_by_id (diagnostic_graph *graph, \ + const char *edge_id) + + Get the edge in ``graph`` with the given id, or null. + + The parameters ``graph`` and ``edge_id`` must be non-null. + + This function was added in :ref:`LIBGDIAGNOSTICS_ABI_3`. + + +.. type:: diagnostic_node + +.. function:: void diagnostic_node_set_label (diagnostic_node *node, \ + const char *label) + + Set the label of ``node`` for use in the value of the + SARIF ``label`` property (SARIF v2.1.0 section 3.40.3). + + The parameter ``node`` must be non-null. + The parameter ``label`` can be null, for clearing any existing + label. + + This function was added in :ref:`LIBGDIAGNOSTICS_ABI_3`. + +.. function:: void diagnostic_node_set_location (diagnostic_node *node, \ + const diagnostic_physical_location *loc) + + Set the physical location of ``node``, if any. + + The parameter ``node`` must be non-null. + The parameter ``loc`` can be null, for clearing any existing + location. + + If set, the value will be used by SARIF sinks within the + ``location`` property (SARIF v2.1.0 section 3.40.4). + + This function was added in :ref:`LIBGDIAGNOSTICS_ABI_3`. + +.. function:: void diagnostic_node_set_logical_location (diagnostic_node *node, \ + const diagnostic_logical_location *logical_loc) + + Set the logical location of ``node``, if any. + + The parameter ``node`` must be non-null. + The parameter ``logical_loc`` _can be null, for clearing any existing + location. + + If set, the value will be used by SARIF sinks within the + ``location`` property (SARIF v2.1.0 section 3.40.4). + + This function was added in :ref:`LIBGDIAGNOSTICS_ABI_3`. diff --git a/gcc/doc/libgdiagnostics/topics/index.rst b/gcc/doc/libgdiagnostics/topics/index.rst index 6e14c0f..966f5ef 100644 --- a/gcc/doc/libgdiagnostics/topics/index.rst +++ b/gcc/doc/libgdiagnostics/topics/index.rst @@ -35,4 +35,6 @@ Topic reference execution-paths.rst text-output.rst sarif.rst + graphs.rst ux.rst + compatibility.rst diff --git a/gcc/doc/libgdiagnostics/topics/logical-locations.rst b/gcc/doc/libgdiagnostics/topics/logical-locations.rst index 3fbee83..294d396 100644 --- a/gcc/doc/libgdiagnostics/topics/logical-locations.rst +++ b/gcc/doc/libgdiagnostics/topics/logical-locations.rst @@ -51,6 +51,8 @@ source location This roughly corresponds to the ``kind`` property in SARIF v2.1.0 (`§3.33.7 <https://docs.oasis-open.org/sarif/sarif/v2.1.0/errata01/os/sarif-v2.1.0-errata01-os-complete.html#_Toc141790976>`_). + Kinds within executable code: + .. macro:: DIAGNOSTIC_LOGICAL_LOCATION_KIND_FUNCTION .. macro:: DIAGNOSTIC_LOGICAL_LOCATION_KIND_MEMBER @@ -67,6 +69,32 @@ source location .. macro:: DIAGNOSTIC_LOGICAL_LOCATION_KIND_VARIABLE + Kinds within XML or HTML documents: + + .. macro:: DIAGNOSTIC_LOGICAL_LOCATION_KIND_ELEMENT + + .. macro:: DIAGNOSTIC_LOGICAL_LOCATION_KIND_ATTRIBUTE + + .. macro:: DIAGNOSTIC_LOGICAL_LOCATION_KIND_TEXT + + .. macro:: DIAGNOSTIC_LOGICAL_LOCATION_KIND_COMMENT + + .. macro:: DIAGNOSTIC_LOGICAL_LOCATION_KIND_PROCESSING_INSTRUCTION + + .. macro:: DIAGNOSTIC_LOGICAL_LOCATION_KIND_DTD + + .. macro:: DIAGNOSTIC_LOGICAL_LOCATION_KIND_DECLARATION + + Kinds within JSON documents: + + .. macro:: DIAGNOSTIC_LOGICAL_LOCATION_KIND_OBJECT + + .. macro:: DIAGNOSTIC_LOGICAL_LOCATION_KIND_ARRAY + + .. macro:: DIAGNOSTIC_LOGICAL_LOCATION_KIND_PROPERTY + + .. macro:: DIAGNOSTIC_LOGICAL_LOCATION_KIND_VALUE + ``parent`` can be NULL; if non-NULL it can be used to express tree-like nesting of logical locations, such as in:: @@ -92,7 +120,7 @@ source location "equal" input values on the same :type:`diagnostic_manager` will return the same instance of :type:`diagnostic_logical_location`. "Equal" here includes different string buffers that compare as equal with - :func:``strcmp`. + :func:`strcmp`. .. function:: void diagnostic_manager_debug_dump_logical_location (const diagnostic_manager *diag_mgr, \ const diagnostic_logical_location *loc, \ @@ -113,3 +141,29 @@ Associating diagnostics with locations Set the logical location of ``diag``. ``diag`` must be non-NULL; ``logical_loc`` can be NULL. + +Accessors +********* + +The following functions can be used to access the data that was passed to a +:type:`diagnostic_logical_location` when it was created. In each case, the +``loc`` parameter must be non-NULL. The return values will point +at *copies* of the original buffer owned by the +:type:`diagnostic_logical_location`, or be null. + +.. function:: enum diagnostic_logical_location_kind_t diagnostic_logical_location_get_kind (const diagnostic_logical_location *loc) + +.. function:: const diagnostic_logical_location *diagnostic_logical_location_get_parent (const diagnostic_logical_location *loc) + +.. function:: const char *diagnostic_logical_location_get_short_name (const diagnostic_logical_location *loc) + +.. function:: const char *diagnostic_logical_location_get_fully_qualified_name (const diagnostic_logical_location *loc) + +.. function:: const char *diagnostic_logical_location_get_decorated_name (const diagnostic_logical_location *loc) + +The above accessors were added in :ref:`LIBGDIAGNOSTICS_ABI_1`; you can +test for their presence using + + .. code-block:: c + + #ifdef LIBDIAGNOSTICS_HAVE_LOGICAL_LOCATION_ACCESSORS diff --git a/gcc/doc/libgdiagnostics/tutorial/02-physical-locations.rst b/gcc/doc/libgdiagnostics/tutorial/02-physical-locations.rst index 95b95ca..e64b668 100644 --- a/gcc/doc/libgdiagnostics/tutorial/02-physical-locations.rst +++ b/gcc/doc/libgdiagnostics/tutorial/02-physical-locations.rst @@ -112,10 +112,10 @@ leading to output like this:: foo.c:17: error: can't find 'foo.h'" 17 | #include <foo.h> -where libgdiagnostics will attempt to load the source file and +where libgdiagnostics will attempt to load ``foo.c`` and quote the pertinent line. -If libgdiagnostics cannot open the file, it will merely print:: +If libgdiagnostics cannot open ``foo.c``, it will merely print:: foo.c:17: error: can't find 'foo.h' @@ -160,14 +160,15 @@ On compiling and running the program, we should get this output:: 17 | #include <foo.h> | ^~~~~ -where libgdiagnostics will attempt to load the source file and +where libgdiagnostics will attempt to load ``foo.c`` and underling the pertinent part of the given line. -If libgdiagnostics cannot open the file, it will merely print:: +If libgdiagnostics cannot open ``foo.c``, it will merely print:: foo.c:17:8: error: can't find 'foo.h' -A range can span multiple lines within the same file. +A range can span multiple lines within the same file, but cannot +span multiple files. As before, you can use :func:`diagnostic_manager_debug_dump_location` to dump the locations. For the above example:: diff --git a/gcc/doc/md.texi b/gcc/doc/md.texi index ae7a601..28159b2 100644 --- a/gcc/doc/md.texi +++ b/gcc/doc/md.texi @@ -2171,12 +2171,6 @@ VFP floating-point registers @code{d0}-@code{d31} and the appropriate subset @code{d0}-@code{d15} based on command line options. Used for 64 bit values only. Not valid for Thumb1. -@item y -The iWMMX co-processor registers. - -@item z -The iWMMX GR registers. - @item G The floating-point constant 0.0 @@ -2210,9 +2204,6 @@ A symbol in the text segment of the current file @item Uv A memory reference suitable for VFP load/store insns (reg+constant offset) -@item Uy -A memory reference suitable for iWMMXt load/store instructions. - @item Uq A memory reference suitable for the ARMv4 ldrsb instruction. @end table @@ -2927,6 +2918,9 @@ A signed 16-bit constant. A memory operand whose address is formed by a base register and offset that is suitable for use in instructions with the same addressing mode as @code{st.w} and @code{ld.w}. +@item q +A general-purpose register except for $r0 and $r1 (for the csrxchg +instruction) @item I A signed 12-bit constant (for arithmetic instructions). @item K @@ -3703,6 +3697,9 @@ RVC general purpose register (x8-x15). RVC floating-point registers (f8-f15), if available, reuse GPR as FPR when use zfinx. +@item cR +Even-odd RVC general purpose register pair. + @item R Even-odd general purpose register pair. @@ -5000,8 +4997,8 @@ This pattern is not allowed to @code{FAIL}. Like @samp{vec_load_lanes@var{m}@var{n}}, but takes an additional mask operand (operand 2) that specifies which elements of the destination vectors should be loaded. Other elements of the destination vectors are -taken from operand 3, which is an else operand similar to the one in -@code{maskload}. +taken from operand 3, which is an else operand in the subvector mode +@var{n}, similar to the one in @code{maskload}. The operation is equivalent to: @smallexample diff --git a/gcc/doc/riscv-ext.texi b/gcc/doc/riscv-ext.texi new file mode 100644 index 0000000..c3ed1bf --- /dev/null +++ b/gcc/doc/riscv-ext.texi @@ -0,0 +1,717 @@ +@c Copyright (C) 2025 Free Software Foundation, Inc. +@c This is part of the GCC manual. +@c For copying conditions, see the file gcc/doc/include/fdl.texi. + +@c This file is generated automatically using +@c gcc/config/riscv/gen-riscv-ext-texi.cc from: +@c gcc/config/riscv/riscv-ext.def +@c gcc/config/riscv/riscv-opts.h + +@c Please *DO NOT* edit manually. + +@multitable @columnfractions .10 .10 .80 +@headitem Extension Name @tab Supported Version @tab Description + +@item g +@tab - +@tab General-purpose computing base extension, @samp{g} will expand to +@samp{i}, @samp{m}, @samp{a}, @samp{f}, @samp{d}, @samp{zicsr} and +@samp{zifencei}. + +@item e +@tab 2.0 +@tab Reduced base integer extension + +@item i +@tab 2.0 2.1 +@tab Base integer extension + +@item m +@tab 2.0 +@tab Integer multiplication and division extension + +@item a +@tab 2.0 2.1 +@tab Atomic extension + +@item f +@tab 2.0 2.2 +@tab Single-precision floating-point extension + +@item d +@tab 2.0 2.2 +@tab Double-precision floating-point extension + +@item c +@tab 2.0 +@tab Compressed extension + +@item b +@tab 1.0 +@tab b extension + +@item v +@tab 1.0 +@tab Vector extension + +@item h +@tab 1.0 +@tab Hypervisor extension + +@item zic64b +@tab 1.0 +@tab Cache block size isf 64 bytes + +@item zicbom +@tab 1.0 +@tab Cache-block management extension + +@item zicbop +@tab 1.0 +@tab Cache-block prefetch extension + +@item zicboz +@tab 1.0 +@tab Cache-block zero extension + +@item ziccamoa +@tab 1.0 +@tab Main memory supports all atomics in A + +@item ziccif +@tab 1.0 +@tab Main memory supports instruction fetch with atomicity requirement + +@item zicclsm +@tab 1.0 +@tab Main memory supports misaligned loads/stores + +@item ziccrse +@tab 1.0 +@tab Main memory supports forward progress on LR/SC sequences + +@item zicfilp +@tab 1.0 +@tab zicfilp extension + +@item zicfiss +@tab 1.0 +@tab zicfiss extension + +@item zicntr +@tab 2.0 +@tab Standard extension for base counters and timers + +@item zicond +@tab 1.0 +@tab Integer conditional operations extension + +@item zicsr +@tab 2.0 +@tab Control and status register access extension + +@item zifencei +@tab 2.0 +@tab Instruction-fetch fence extension + +@item zihintntl +@tab 1.0 +@tab Non-temporal locality hints extension + +@item zihintpause +@tab 2.0 +@tab Pause hint extension + +@item zihpm +@tab 2.0 +@tab Standard extension for hardware performance counters + +@item zimop +@tab 1.0 +@tab zimop extension + +@item zilsd +@tab 1.0 +@tab Load/Store pair instructions extension + +@item zmmul +@tab 1.0 +@tab Integer multiplication extension + +@item za128rs +@tab 1.0 +@tab Reservation set size of 128 bytes + +@item za64rs +@tab 1.0 +@tab Reservation set size of 64 bytes + +@item zaamo +@tab 1.0 +@tab zaamo extension + +@item zabha +@tab 1.0 +@tab zabha extension + +@item zacas +@tab 1.0 +@tab zacas extension + +@item zalrsc +@tab 1.0 +@tab zalrsc extension + +@item zawrs +@tab 1.0 +@tab Wait-on-reservation-set extension + +@item zama16b +@tab 1.0 +@tab Zama16b extension, Misaligned loads, stores, and AMOs to main memory regions that do not cross a naturally aligned 16-byte boundary are atomic. + +@item zfa +@tab 1.0 +@tab Additional floating-point extension + +@item zfbfmin +@tab 1.0 +@tab zfbfmin extension + +@item zfh +@tab 1.0 +@tab Half-precision floating-point extension + +@item zfhmin +@tab 1.0 +@tab Minimal half-precision floating-point extension + +@item zfinx +@tab 1.0 +@tab Single-precision floating-point in integer registers extension + +@item zdinx +@tab 1.0 +@tab Double-precision floating-point in integer registers extension + +@item zca +@tab 1.0 +@tab Integer compressed instruction extension + +@item zcb +@tab 1.0 +@tab Simple compressed instruction extension + +@item zcd +@tab 1.0 +@tab Compressed double-precision floating point loads and stores extension + +@item zce +@tab 1.0 +@tab Compressed instruction extensions for embedded processors + +@item zcf +@tab 1.0 +@tab Compressed single-precision floating point loads and stores extension + +@item zcmop +@tab 1.0 +@tab zcmop extension + +@item zcmp +@tab 1.0 +@tab Compressed push pop extension + +@item zcmt +@tab 1.0 +@tab Table jump instruction extension + +@item zclsd +@tab 1.0 +@tab Compressed load/store pair instructions extension + +@item zba +@tab 1.0 +@tab Address calculation extension + +@item zbb +@tab 1.0 +@tab Basic bit manipulation extension + +@item zbc +@tab 1.0 +@tab Carry-less multiplication extension + +@item zbkb +@tab 1.0 +@tab Cryptography bit-manipulation extension + +@item zbkc +@tab 1.0 +@tab Cryptography carry-less multiply extension + +@item zbkx +@tab 1.0 +@tab Cryptography crossbar permutation extension + +@item zbs +@tab 1.0 +@tab Single-bit operation extension + +@item zk +@tab 1.0 +@tab Standard scalar cryptography extension + +@item zkn +@tab 1.0 +@tab NIST algorithm suite extension + +@item zknd +@tab 1.0 +@tab AES Decryption extension + +@item zkne +@tab 1.0 +@tab AES Encryption extension + +@item zknh +@tab 1.0 +@tab Hash function extension + +@item zkr +@tab 1.0 +@tab Entropy source extension + +@item zks +@tab 1.0 +@tab ShangMi algorithm suite extension + +@item zksed +@tab 1.0 +@tab SM4 block cipher extension + +@item zksh +@tab 1.0 +@tab SM3 hash function extension + +@item zkt +@tab 1.0 +@tab Data independent execution latency extension + +@item ztso +@tab 1.0 +@tab Total store ordering extension + +@item zvbb +@tab 1.0 +@tab Vector basic bit-manipulation extension + +@item zvbc +@tab 1.0 +@tab Vector carryless multiplication extension + +@item zve32f +@tab 1.0 +@tab Vector extensions for embedded processors + +@item zve32x +@tab 1.0 +@tab Vector extensions for embedded processors + +@item zve64d +@tab 1.0 +@tab Vector extensions for embedded processors + +@item zve64f +@tab 1.0 +@tab Vector extensions for embedded processors + +@item zve64x +@tab 1.0 +@tab Vector extensions for embedded processors + +@item zvfbfmin +@tab 1.0 +@tab Vector BF16 converts extension + +@item zvfbfwma +@tab 1.0 +@tab zvfbfwma extension + +@item zvfh +@tab 1.0 +@tab Vector half-precision floating-point extension + +@item zvfhmin +@tab 1.0 +@tab Vector minimal half-precision floating-point extension + +@item zvkb +@tab 1.0 +@tab Vector cryptography bit-manipulation extension + +@item zvkg +@tab 1.0 +@tab Vector GCM/GMAC extension + +@item zvkn +@tab 1.0 +@tab Vector NIST Algorithm Suite extension, @samp{zvkn} will expand to + +@item zvknc +@tab 1.0 +@tab Vector NIST Algorithm Suite with carryless multiply extension, @samp{zvknc} + +@item zvkned +@tab 1.0 +@tab Vector AES block cipher extension + +@item zvkng +@tab 1.0 +@tab Vector NIST Algorithm Suite with GCM extension, @samp{zvkng} will expand + +@item zvknha +@tab 1.0 +@tab Vector SHA-2 secure hash extension + +@item zvknhb +@tab 1.0 +@tab Vector SHA-2 secure hash extension + +@item zvks +@tab 1.0 +@tab Vector ShangMi algorithm suite extension, @samp{zvks} will expand + +@item zvksc +@tab 1.0 +@tab Vector ShangMi algorithm suite with carryless multiplication extension, + +@item zvksed +@tab 1.0 +@tab Vector SM4 Block Cipher extension + +@item zvksg +@tab 1.0 +@tab Vector ShangMi algorithm suite with GCM extension, @samp{zvksg} will expand + +@item zvksh +@tab 1.0 +@tab Vector SM3 Secure Hash extension + +@item zvkt +@tab 1.0 +@tab Vector data independent execution latency extension + +@item zvl1024b +@tab 1.0 +@tab Minimum vector length standard extensions + +@item zvl128b +@tab 1.0 +@tab Minimum vector length standard extensions + +@item zvl16384b +@tab 1.0 +@tab zvl16384b extension + +@item zvl2048b +@tab 1.0 +@tab Minimum vector length standard extensions + +@item zvl256b +@tab 1.0 +@tab Minimum vector length standard extensions + +@item zvl32768b +@tab 1.0 +@tab zvl32768b extension + +@item zvl32b +@tab 1.0 +@tab Minimum vector length standard extensions + +@item zvl4096b +@tab 1.0 +@tab Minimum vector length standard extensions + +@item zvl512b +@tab 1.0 +@tab Minimum vector length standard extensions + +@item zvl64b +@tab 1.0 +@tab Minimum vector length standard extensions + +@item zvl65536b +@tab 1.0 +@tab zvl65536b extension + +@item zvl8192b +@tab 1.0 +@tab zvl8192b extension + +@item zhinx +@tab 1.0 +@tab Half-precision floating-point in integer registers extension + +@item zhinxmin +@tab 1.0 +@tab Minimal half-precision floating-point in integer registers extension + +@item sdtrig +@tab 1.0 +@tab sdtrig extension + +@item sha +@tab 1.0 +@tab The augmented hypervisor extension + +@item shcounterenw +@tab 1.0 +@tab Support writeable enables for any supported counter + +@item shgatpa +@tab 1.0 +@tab SvNNx4 mode supported for all modes supported by satp + +@item shlcofideleg +@tab 1.0 +@tab Delegating LCOFI interrupts to VS-mode + +@item shtvala +@tab 1.0 +@tab The htval register provides all needed values + +@item shvstvala +@tab 1.0 +@tab The vstval register provides all needed values + +@item shvstvecd +@tab 1.0 +@tab The vstvec register supports Direct mode + +@item shvsatpa +@tab 1.0 +@tab The vsatp register supports all modes supported by satp + +@item smaia +@tab 1.0 +@tab Advanced interrupt architecture extension + +@item smcntrpmf +@tab 1.0 +@tab Cycle and instret privilege mode filtering + +@item smcsrind +@tab 1.0 +@tab Machine-Level Indirect CSR Access + +@item smepmp +@tab 1.0 +@tab PMP Enhancements for memory access and execution prevention on Machine mode + +@item smmpm +@tab 1.0 +@tab smmpm extension + +@item smnpm +@tab 1.0 +@tab smnpm extension + +@item smrnmi +@tab 1.0 +@tab Resumable non-maskable interrupts + +@item smstateen +@tab 1.0 +@tab State enable extension + +@item smdbltrp +@tab 1.0 +@tab Double Trap Extensions + +@item ssaia +@tab 1.0 +@tab Advanced interrupt architecture extension for supervisor-mode + +@item ssccptr +@tab 1.0 +@tab Main memory supports page table reads + +@item sscofpmf +@tab 1.0 +@tab Count overflow & filtering extension + +@item sscounterenw +@tab 1.0 +@tab Support writeable enables for any supported counter + +@item sscsrind +@tab 1.0 +@tab Supervisor-Level Indirect CSR Access + +@item ssnpm +@tab 1.0 +@tab ssnpm extension + +@item sspm +@tab 1.0 +@tab sspm extension + +@item ssstateen +@tab 1.0 +@tab State-enable extension for supervisor-mode + +@item sstc +@tab 1.0 +@tab Supervisor-mode timer interrupts extension + +@item sstvala +@tab 1.0 +@tab Stval provides all needed values + +@item sstvecd +@tab 1.0 +@tab Stvec supports Direct mode + +@item ssstrict +@tab 1.0 +@tab ssstrict extension + +@item ssdbltrp +@tab 1.0 +@tab Double Trap Extensions + +@item ssu64xl +@tab 1.0 +@tab UXLEN=64 must be supported + +@item supm +@tab 1.0 +@tab supm extension + +@item svinval +@tab 1.0 +@tab Fine-grained address-translation cache invalidation extension + +@item svnapot +@tab 1.0 +@tab NAPOT translation contiguity extension + +@item svpbmt +@tab 1.0 +@tab Page-based memory types extension + +@item svvptc +@tab 1.0 +@tab svvptc extension + +@item svadu +@tab 1.0 +@tab Hardware Updating of A/D Bits extension + +@item svade +@tab 1.0 +@tab Cause exception when hardware updating of A/D bits is disabled + +@item svbare +@tab 1.0 +@tab Satp mode bare is supported + +@item xcvalu +@tab 1.0 +@tab Core-V miscellaneous ALU extension + +@item xcvbi +@tab 1.0 +@tab xcvbi extension + +@item xcvelw +@tab 1.0 +@tab Core-V event load word extension + +@item xcvmac +@tab 1.0 +@tab Core-V multiply-accumulate extension + +@item xcvsimd +@tab 1.0 +@tab xcvsimd extension + +@item xsfcease +@tab 1.0 +@tab xsfcease extension + +@item xsfvcp +@tab 1.0 +@tab xsfvcp extension + +@item xsfvfnrclipxfqf +@tab 1.0 +@tab xsfvfnrclipxfqf extension + +@item xsfvqmaccdod +@tab 1.0 +@tab xsfvqmaccdod extension + +@item xsfvqmaccqoq +@tab 1.0 +@tab xsfvqmaccqoq extension + +@item xtheadba +@tab 1.0 +@tab T-head address calculation extension + +@item xtheadbb +@tab 1.0 +@tab T-head basic bit-manipulation extension + +@item xtheadbs +@tab 1.0 +@tab T-head single-bit instructions extension + +@item xtheadcmo +@tab 1.0 +@tab T-head cache management operations extension + +@item xtheadcondmov +@tab 1.0 +@tab T-head conditional move extension + +@item xtheadfmemidx +@tab 1.0 +@tab T-head indexed memory operations for floating-point registers extension + +@item xtheadfmv +@tab 1.0 +@tab T-head double floating-point high-bit data transmission extension + +@item xtheadint +@tab 1.0 +@tab T-head acceleration interruption extension + +@item xtheadmac +@tab 1.0 +@tab T-head multiply-accumulate extension + +@item xtheadmemidx +@tab 1.0 +@tab T-head indexed memory operation extension + +@item xtheadmempair +@tab 1.0 +@tab T-head two-GPR memory operation extension + +@item xtheadsync +@tab 1.0 +@tab T-head multi-core synchronization extension + +@item xtheadvector +@tab 1.0 +@tab xtheadvector extension + +@item xventanacondops +@tab 1.0 +@tab Ventana integer conditional operations extension + +@end multitable diff --git a/gcc/doc/sourcebuild.texi b/gcc/doc/sourcebuild.texi index c29cd3f..85fb810 100644 --- a/gcc/doc/sourcebuild.texi +++ b/gcc/doc/sourcebuild.texi @@ -215,10 +215,10 @@ man pages and support for converting the installation manual to HTML@. @xref{Documentation}. @item ginclude -System headers installed by GCC, mainly those required by the C -standard of freestanding implementations. @xref{Headers, , Headers -Installed by GCC}, for details of when these and other headers are -installed. +System headers installed by GCC, mainly those defined by the C +standard that do not declare functions with external linkage. +@xref{Headers, , Headers Installed by GCC}, for details of when these +and other headers are installed. @item po Message catalogs with translations of messages produced by GCC into @@ -326,7 +326,8 @@ Headers Installed by GCC}, for more information about the In general, GCC expects the system C library to provide most of the headers to be used with it. However, GCC will fix those headers if necessary to make them work with GCC, and will install some headers -required of freestanding implementations. These headers are installed +of its own, mainly headers that do not declare functions with external +linkage. These headers are installed in @file{@var{libsubdir}/include}. Headers for non-C runtime libraries are also installed by GCC; these are not documented here. (FIXME: document them somewhere.) @@ -351,8 +352,8 @@ representation of floating point numbers. GCC also installs its own version of @code{<limits.h>}; this is generated from @file{glimits.h}, together with @file{limitx.h} and @file{limity.h} if the system also has its own version of -@code{<limits.h>}. (GCC provides its own header because it is -required of ISO C freestanding implementations, but needs to include +@code{<limits.h>}. (GCC provides its own header because it does not +declare functions with external linkage, but needs to include the system header from its own header as well because other standards such as POSIX specify additional values to be defined in @code{<limits.h>}.) The system's @code{<limits.h>} header is used via @@ -1975,6 +1976,9 @@ at plain @option{-O2}. @item tls Target supports thread-local storage. +@item tls_link +Target supports linking TLS executables. + @item tls_native Target supports native (rather than emulated) thread-local storage. @@ -2042,10 +2046,6 @@ ARM target uses emulated floating point operations. ARM target supports @code{-mfpu=vfp -mfloat-abi=hard}. Some multilibs may be incompatible with these options. -@item arm_iwmmxt_ok -ARM target supports @code{-mcpu=iwmmxt}. -Some multilibs may be incompatible with this option. - @item arm_neon ARM target supports generating NEON instructions. @@ -2373,6 +2373,12 @@ whether it does so by default). @itemx aarch64_sve1024_hw @itemx aarch64_sve2048_hw Like @code{aarch64_sve_hw}, but also test for an exact hardware vector length. +@item aarch64_sve2_hw +AArch64 target that is able to generate and execute SVE2 code (regardless of +whether it does so by default). +@item aarch64_sve2p1_hw +AArch64 target that is able to generate and execute SVE2.1 code (regardless of +whether it does so by default). @item aarch64_fjcvtzs_hw AArch64 target that is able to generate and execute armv8.3-a FJCVTZS @@ -2623,15 +2629,9 @@ Target supports compiling @code{avx} instructions. @item avx_runtime Target supports the execution of @code{avx} instructions. -@item avx10.1-256 -Target supports the execution of @code{avx10.1-256} instructions. - @item avx10.1 Target supports the execution of @code{avx10.1} instructions. -@item avx10.1-512 -Target supports the execution of @code{avx10.1-512} instructions. - @item avx10.2 Target supports the execution of @code{avx10.2} instructions. @@ -2957,6 +2957,9 @@ Target supports @code{sysconf}. @item trampolines Target supports trampolines. +@item variadic_mi_thunk +Target supports C++ virtual variadic function calls with multiple inheritance. + @item two_plus_gigs Target supports linking programs with 2+GiB of data. @@ -3012,6 +3015,9 @@ Note that this is orthogonal to effective-target @code{exceptions_enabled}. Testing configuration has exception handling enabled. Note that this is orthogonal to effective-target @code{exceptions}. +@item using_sjlj_exceptions +Target uses @code{setjmp} and @code{longjmp} for implementing exceptions. + @item fgraphite Target supports Graphite optimizations. diff --git a/gcc/doc/standards.texi b/gcc/doc/standards.texi index bbae350..0d765b1 100644 --- a/gcc/doc/standards.texi +++ b/gcc/doc/standards.texi @@ -96,8 +96,8 @@ A new edition of the ISO C standard was published in 1999 as ISO/IEC development, drafts of this standard version were referred to as @dfn{C9X}.) GCC has substantially complete support for this standard version; see -@uref{https://gcc.gnu.org/c99status.html} for details. To select this -standard, use @option{-std=c99} or @option{-std=iso9899:1999}. +@uref{https://gcc.gnu.org/projects/c-status.html} for details. To select +this standard, use @option{-std=c99} or @option{-std=iso9899:1999}. Errors in the 1999 ISO C standard were corrected in three Technical Corrigenda published in 2001, 2004 and 2007. GCC does not support the @@ -152,7 +152,9 @@ library facilities: those in @code{<float.h>}, @code{<limits.h>}, @code{<iso646.h>}; since C99, also those in @code{<stdbool.h>} and @code{<stdint.h>}; and since C11, also those in @code{<stdalign.h>} and @code{<stdnoreturn.h>}. In addition, complex types, added in C99, are not -required for freestanding implementations. +required for freestanding implementations. Since C23, freestanding +implementations are required to support a larger range of library +facilities, including some functions from other headers. The standard also defines two environments for programs, a @dfn{freestanding environment}, required of all implementations and @@ -167,13 +169,13 @@ a program using the facilities of an operating system is an example of a program running in a hosted environment. @opindex ffreestanding -GCC aims towards being usable as a conforming freestanding -implementation, or as the compiler for a conforming hosted -implementation. By default, it acts as the compiler for a hosted +GCC aims towards being usable as the compiler for a conforming +freestanding or hosted implementation. +By default, it acts as the compiler for a hosted implementation, defining @code{__STDC_HOSTED__} as @code{1} and presuming that when the names of ISO C functions are used, they have -the semantics defined in the standard. To make it act as a conforming -freestanding implementation for a freestanding environment, use the +the semantics defined in the standard. To make it act as the compiler +for a freestanding environment, use the option @option{-ffreestanding}; it then defines @code{__STDC_HOSTED__} to @code{0} and does not make assumptions about the meanings of function names from the standard library, with exceptions @@ -181,12 +183,24 @@ noted below. To build an OS kernel, you may well still need to make your own arrangements for linking and startup. @xref{C Dialect Options,,Options Controlling C Dialect}. -GCC does not provide the library facilities required only of hosted -implementations, nor yet all the facilities required by C99 of -freestanding implementations on all platforms. -To use the facilities of a hosted -environment, you need to find them elsewhere (for example, in the -GNU C library). @xref{Standard Libraries,,Standard Libraries}. +GCC generally provides library facilities in headers that do not +declare functions with external linkage (which includes the headers +required by C11 and before to be provided by freestanding +implementations), but not those included in other headers. +Additionally, GCC provides @code{<stdatomic.h>}, even though it +declares some functions with external linkage (which are provided in +@code{libatomic}). On a few platforms, some of the headers not +declaring functions with external linkage are instead obtained from +the OS's C library, which may mean that they lack support for features +from more recent versions of the C standard that are supported in +GCC's own versions of those headers. On some platforms, GCC provides +@code{<tgmath.h>} (but this implementation does not support interfaces +added in C23). + +To use the facilities of a hosted environment, and some of the +facilities required in a freestanding environment by C23, you need to +find them elsewhere (for example, in the GNU C library). +@xref{Standard Libraries,,Standard Libraries}. Most of the compiler support routines used by GCC are present in @file{libgcc}, but there are a few exceptions. GCC requires the diff --git a/gcc/doc/tm.texi b/gcc/doc/tm.texi index a96700c..5e30564 100644 --- a/gcc/doc/tm.texi +++ b/gcc/doc/tm.texi @@ -4774,10 +4774,6 @@ that element as the canonical location and ignore the others. The m68k port uses this type of @code{parallel} to return pointers in both @samp{%a0} (the canonical location) and @samp{%d0}. -If @code{TARGET_PROMOTE_FUNCTION_RETURN} returns true, you must apply -the same promotion rules specified in @code{PROMOTE_MODE} if -@var{valtype} is a scalar type. - If the precise function being called is known, @var{func} is a tree node (@code{FUNCTION_DECL}) for it; otherwise, @var{func} is a null pointer. This makes it possible to use a different value-returning diff --git a/gcc/doc/trouble.texi b/gcc/doc/trouble.texi index 15ced5f..a2e6de4 100644 --- a/gcc/doc/trouble.texi +++ b/gcc/doc/trouble.texi @@ -494,10 +494,12 @@ as to use the proper set, but you'll have to do this by hand. @section Standard Libraries @opindex Wall -GCC by itself attempts to be a conforming freestanding implementation. +GCC by itself attempts to provide the compiler part of a conforming +implementation, but only a limited subset of the library part of such +an implementation. @xref{Standards,,Language Standards Supported by GCC}, for details of -what this means. Beyond the library facilities required of such an -implementation, the rest of the C library is supplied by the vendor of +what this means. Beyond the limited library facilities described +there, the rest of the C library is supplied by the vendor of the operating system. If that C library doesn't conform to the C standards, then your programs might get warnings (especially when using @option{-Wall}) that you don't expect. diff --git a/gcc/doc/ux.texi b/gcc/doc/ux.texi index 2428d1a..22df88f 100644 --- a/gcc/doc/ux.texi +++ b/gcc/doc/ux.texi @@ -407,9 +407,12 @@ Use @code{auto_diagnostic_group} when issuing multiple related diagnostics (seen in various examples on this page). This informs the diagnostic subsystem that all diagnostics issued within the lifetime of the @code{auto_diagnostic_group} are related. For example, -@option{-fdiagnostics-format=json} will treat the first diagnostic +@option{-fdiagnostics-add-output=sarif} will treat the first diagnostic emitted within the group as a top-level diagnostic, and all subsequent -diagnostics within the group as its children. +diagnostics within the group as its children. Also, if a warning in the +group is inhibited at nesting depth D, all subsequent notes at that depth +or deeper will be inhibited as well, until an error or another warning +is emitted, the depth decreases below D, or the group is popped. @subsection Quoting Text should be quoted by either using the @samp{q} modifier in a directive |