diff options
Diffstat (limited to 'gcc/doc')
| -rw-r--r-- | gcc/doc/cfg.texi | 10 | ||||
| -rw-r--r-- | gcc/doc/extend.texi | 459 | ||||
| -rw-r--r-- | gcc/doc/gm2.texi | 8 | ||||
| -rw-r--r-- | gcc/doc/install.texi | 6 | ||||
| -rw-r--r-- | gcc/doc/invoke.texi | 504 | ||||
| -rw-r--r-- | gcc/doc/libgdiagnostics/topics/compatibility.rst | 179 | ||||
| -rw-r--r-- | gcc/doc/libgdiagnostics/topics/index.rst | 1 | ||||
| -rw-r--r-- | gcc/doc/libgdiagnostics/topics/logical-locations.rst | 53 | ||||
| -rw-r--r-- | gcc/doc/sourcebuild.texi | 6 | ||||
| -rw-r--r-- | gcc/doc/tm.texi | 4 | ||||
| -rw-r--r-- | gcc/doc/ux.texi | 5 |
11 files changed, 920 insertions, 315 deletions
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 a49b1cd..212d248 100644 --- a/gcc/doc/extend.texi +++ b/gcc/doc/extend.texi @@ -1728,23 +1728,24 @@ write-only accesses to objects that are never read from. Such accesses may be diagnosed by warnings such as @option{-Wstringop-overflow}, @option{-Wuninitialized}, @option{-Wunused}, and others. -The @code{access} attribute specifies that a function to whose by-reference -arguments the attribute applies accesses the referenced object according to -@var{access-mode}. The @var{access-mode} argument is required and must be -one of four names: @code{read_only}, @code{read_write}, @code{write_only}, -or @code{none}. The remaining two are positional arguments. - -The 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 optional @var{size-index} positional argument denotes a function +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 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} 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. @@ -1756,7 +1757,7 @@ is zero, the referenced object must be initialized. The mode implies a stronger guarantee than the @code{const} qualifier which, when cast away from a pointer, does not prevent the pointed-to object from being modified. Examples of the use of the @code{read_only} access mode is the argument to -the @code{puts} function, or the second and third arguments to +the @code{puts} function, or the second argument to the @code{memcpy} function. @smallexample @@ -1796,12 +1797,13 @@ __attribute__ ((access (write_only, 1, 2), access (read_write, 3))) int fgets (char*, int, FILE*); @end smallexample -The access mode @code{none} specifies that the pointer to which it applies +The access mode @code{none} specifies that the pointer argument +to which it applies is not used to access the referenced object at all. Unless the pointer is -null the pointed-to object must exist and have at least the size as denoted +null, the pointed-to object must exist and have at least the size as denoted by the @var{size-index} argument. When the optional @var{size-index} -argument is omitted for an argument of @code{void*} type the actual pointer -agument is ignored. The referenced object need not be initialized. +argument is omitted for an argument of @code{void*} type, the actual pointer +argument is ignored. The referenced object need not be initialized. The mode is intended to be used as a means to help validate the expected object size, for example in functions that call @code{__builtin_object_size}. @xref{Object Size Checking}. @@ -1812,7 +1814,8 @@ an access @strong{will} happen. Also, the @code{access} attribute does not imply the attribute @code{nonnull} nor the attribute @code{nonnull_if_nonzero}; it may be appropriate to add both attributes at the declaration of a function that unconditionally manipulates a buffer via a pointer argument. See the -@code{nonnull} or @code{nonnull_if_nonzero} attributes for more information and +@code{nonnull} or @code{nonnull_if_nonzero} function attributes, +documented later in this section, for more information and caveats. @cindex @code{alias} function attribute @@ -1930,6 +1933,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 @@ -2035,24 +2045,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 @@ -9303,7 +9321,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(); @@ -9313,12 +9331,78 @@ 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 @@ -9898,50 +9982,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 @@ -12193,15 +12306,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. @@ -12218,32 +12322,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} @@ -12265,16 +12354,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} @@ -12290,76 +12369,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 @@ -12562,6 +12585,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} @@ -12943,7 +12967,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. @@ -12954,6 +12979,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. @@ -13643,22 +13669,77 @@ If the operand of the @code{__alignof__} expression is a function, the expression evaluates to the alignment of the function which may be specified by attribute @code{aligned} (@pxref{Common Function Attributes}). -@node Incomplete Enums -@subsection Incomplete @code{enum} Types +@node Enum Extensions +@subsection Extensions to @code{enum} Type Declarations +@anchor{Incomplete Enums} +@cindex @code{enum} extensions +@cindex base type of an @code{enum} +@cindex underlying type of an @code{enum} +@cindex forward declaration of an @code{enum} +@cindex opaque @code{enum} types +@cindex incomplete @code{enum} types + +The C23 and C++11 standards added new syntax to specify the underlying +type of an @code{enum} type. For example, + +@smallexample +enum pet : unsigned char @{ CAT, DOG, ROCK @}; +@end smallexample + +In GCC, this feature is supported as an extension in all older +dialects of C and C++ as well. For C++ dialects before C++11, use +@option{-Wno-c++11-extensions} to silence the associated warnings. + +You can also forward-declare an @code{enum} type, without specifying +its possible values. The enumerators are supplied in a later +redeclaration of the type, which must match the underlying type of the +first declaration. -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. +@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 + +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. -This extension is not supported by GNU C++. +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. @@ -13920,6 +14001,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 @@ -30241,11 +30341,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: @@ -30259,6 +30359,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/gm2.texi b/gcc/doc/gm2.texi index 8baee24..cb52e8c 100644 --- a/gcc/doc/gm2.texi +++ b/gcc/doc/gm2.texi @@ -2699,10 +2699,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 +2720,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/install.texi b/gcc/doc/install.texi index b5509ff..1af0082 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 diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi index b1a0d93..b1964b3 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 @@ -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 @@ -510,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 @@ -575,7 +579,7 @@ Objective-C and Objective-C++ Dialects}. -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 @@ -590,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 @@ -639,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 @@ -672,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 @@ -2196,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 @@ -3001,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 @@ -3578,12 +3589,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} @@ -6041,6 +6059,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 @@ -6144,12 +6167,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 @@ -6177,10 +6200,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}. @@ -6189,15 +6213,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 @@ -6206,11 +6230,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 @@ -6496,7 +6520,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 @@ -6599,27 +6624,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 - -@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: +@opindex Wpsabi +@opindex Wno-psabi +@item -Wpsabi @r{(C, Objective-C, C++ and Objective-C++ only)} -@smallexample -union U @{ - long double ld; - int i; -@}; -@end smallexample +@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. -@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 @@ -6972,6 +6991,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)} @@ -10062,8 +10130,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 @@ -10951,6 +11020,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 @@ -11602,6 +11672,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 @@ -12690,6 +12771,7 @@ complexity than at @option{-O}. -fipa-pure-const -fipa-reference -fipa-reference-addressable +-fivopts -fmerge-constants -fmove-loop-invariants -fmove-loop-stores @@ -12798,6 +12880,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 @@ -12823,17 +12912,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 @@ -13815,6 +13906,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. @@ -14023,6 +14129,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 @@ -14229,6 +14341,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 @@ -14544,11 +14657,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 @@ -14560,12 +14675,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 @@ -15269,32 +15386,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 @@ -15312,6 +15421,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}, @@ -15446,9 +15567,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 @@ -15509,8 +15629,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 @@ -15523,7 +15642,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 @@ -15570,7 +15696,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}. @@ -16468,6 +16595,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 @@ -16793,11 +16929,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. @@ -16859,6 +16990,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. @@ -17113,9 +17257,6 @@ 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 vrp-block-limit Maximum number of basic blocks before VRP switches to a lower memory algorithm. @@ -18323,7 +18464,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 @@ -18331,22 +18473,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. -To override @option{-fcf-protection}, @option{-fcf-protection=none} -needs to be added and then with @option{-fcf-protection=xxx}. +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{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 @@ -20624,6 +20774,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 @@ -21201,8 +21438,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 @@ -21802,11 +22044,13 @@ performance of the code. Permissible values for this option are: @samp{cortex-x2}, @samp{cortex-x3}, @samp{cortex-x4}, @samp{cortex-a510}, @samp{cortex-a520}, @samp{cortex-a520ae}, @samp{cortex-a710}, @samp{cortex-a715}, @samp{cortex-a720}, @samp{cortex-a720ae}, @samp{ampere1}, @samp{ampere1a}, -@samp{ampere1b}, @samp{cobalt-100} and @samp{native}. +@samp{ampere1b}, @samp{cobalt-100}, @samp{apple-m1}, @samp{apple-m2}, +@samp{apple-m3} and @samp{native}. The values @samp{cortex-a57.cortex-a53}, @samp{cortex-a72.cortex-a53}, @samp{cortex-a73.cortex-a35}, @samp{cortex-a73.cortex-a53}, -@samp{cortex-a75.cortex-a55}, @samp{cortex-a76.cortex-a55} specify that GCC +@samp{cortex-a75.cortex-a55}, @samp{cortex-a76.cortex-a55}, +@samp{apple-m1}, @samp{apple-m2}, @samp{apple-m3} specify that GCC should tune for a big.LITTLE system. The value @samp{neoverse-512tvb} specifies that GCC should tune @@ -31288,6 +31532,14 @@ to @samp{zvks} and @samp{zvkg}. @tab 1.0 @tab Supervisor-mode timer interrupts extension. +@item svade +@tab 1.0 +@tab Cause exception when hardware updating of A/D bits is disabled + +@item svadu +@tab 1.0 +@tab Hardware Updating of A/D Bits extension. + @item svinval @tab 1.0 @tab Fine-grained address-translation cache invalidation extension. @@ -31384,8 +31636,9 @@ 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}. +@samp{sifive-x670}, @samp{thead-c906}, @samp{tt-ascalon-d8}, @samp{xiangshan-nanhu}, +@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}. @@ -32393,18 +32646,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 @@ -33259,7 +33512,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}. @@ -34753,7 +35006,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 @@ -34786,7 +35040,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 diff --git a/gcc/doc/libgdiagnostics/topics/compatibility.rst b/gcc/doc/libgdiagnostics/topics/compatibility.rst new file mode 100644 index 0000000..4df6850 --- /dev/null +++ b/gcc/doc/libgdiagnostics/topics/compatibility.rst @@ -0,0 +1,179 @@ +.. 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` diff --git a/gcc/doc/libgdiagnostics/topics/index.rst b/gcc/doc/libgdiagnostics/topics/index.rst index 6e14c0f..6eb3ed6 100644 --- a/gcc/doc/libgdiagnostics/topics/index.rst +++ b/gcc/doc/libgdiagnostics/topics/index.rst @@ -36,3 +36,4 @@ Topic reference text-output.rst sarif.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..184b563 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:: @@ -113,3 +141,28 @@ 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. :type:`const char *` values will point +at copies of the original buffer. + +.. 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/sourcebuild.texi b/gcc/doc/sourcebuild.texi index c29cd3f..65eeecc 100644 --- a/gcc/doc/sourcebuild.texi +++ b/gcc/doc/sourcebuild.texi @@ -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/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/ux.texi b/gcc/doc/ux.texi index 2428d1a..243b3e0 100644 --- a/gcc/doc/ux.texi +++ b/gcc/doc/ux.texi @@ -409,7 +409,10 @@ 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 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 |