extensions, accepted by GCC in C90 mode and in C++.
@menu
-* Statement Exprs:: Putting statements and declarations inside expressions.
-* Local Labels:: Labels local to a block.
-* Labels as Values:: Getting pointers to labels, and computed gotos.
-* Nested Functions:: Nested function in GNU C.
* Nonlocal Gotos:: Nonlocal gotos.
* Constructing Calls:: Dispatching a call to another function.
-* Typeof:: @code{typeof}: referring to the type of an expression.
-* Conditionals:: Omitting the middle operand of a @samp{?:} expression.
* Additional Numeric Types:: Additional sizes and formats, plus complex numbers.
* Aggregate Types:: Extensions to arrays, structs, and unions.
-* Hex Floats:: Hexadecimal floating-point constants.
* Named Address Spaces::Named address spaces.
-* Variadic Macros:: Macros with a variable number of arguments.
-* Escaped Newlines:: Slightly looser rules for escaped newlines.
-* Pointer Arith:: Arithmetic on @code{void}-pointers and function pointers.
-* Variadic Pointer Args:: Pointer arguments to variadic functions.
-* Pointers to Arrays:: Pointers to arrays with qualifiers work as expected.
-* Case Ranges:: `case 1 ... 9' and such.
-* Mixed Labels and Declarations:: Mixing declarations, labels and code.
* Function Attributes:: Declaring that functions have no side effects,
or that they can never return.
* Variable Attributes:: Specifying attributes of variables.
* Enumerator Attributes:: Specifying attributes on enumerators.
* Statement Attributes:: Specifying attributes on statements.
* Attribute Syntax:: Formal syntax for attributes.
-* Function Prototypes:: Prototype declarations and old-style definitions.
-* C++ Comments:: C++ comments are recognized.
-* Dollar Signs:: Dollar sign is allowed in identifiers.
-* Character Escapes:: @samp{\e} stands for the character @key{ESC}.
-* Alignment:: Determining the alignment of a function, type or variable.
* Inline:: Defining inline functions (as fast as macros).
-* Const and Volatile Functions :: GCC interprets these specially in C.
* Volatiles:: What constitutes an access to a volatile object.
* Using Assembly Language with C:: Instructions and extensions for interfacing C with assembler.
-* Alternate Keywords:: @code{__const__}, @code{__asm__}, etc., for header files.
-* Incomplete Enums:: @code{enum foo;}, with details to follow.
-* Function Names:: Printable strings which are the name of the current
- function.
+* Syntax Extensions:: Other extensions to C syntax.
+* Semantic Extensions:: GNU C defines behavior for some non-standard constructs.
* 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.
-* Offsetof:: Special syntax for implementing @code{offsetof}.
* __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
* Target Format Checks:: Format checks specific to particular targets.
* Pragmas:: Pragmas accepted by GCC.
* Thread-Local:: Per-thread variables.
-* Binary constants:: Binary constants using the @samp{0b} prefix.
* OpenMP:: Multiprocessing extensions.
* OpenACC:: Extensions for offloading code to accelerator devices.
@end menu
-@node Statement Exprs
-@section Statements and Declarations in Expressions
-@cindex statements inside expressions
-@cindex declarations inside expressions
-@cindex expressions containing statements
-@cindex macros, statements in expressions
+@node Nonlocal Gotos
+@section Nonlocal Gotos
+@cindex nonlocal gotos
-@c the above section title wrapped and causes an underfull hbox.. i
-@c changed it from "within" to "in". --mew 4feb93
-A compound statement enclosed in parentheses may appear as an expression
-in GNU C@. This allows you to use loops, switches, and local variables
-within an expression.
+GCC provides the built-in functions @code{__builtin_setjmp} and
+@code{__builtin_longjmp} which are similar to, but not interchangeable
+with, the C library functions @code{setjmp} and @code{longjmp}.
+The built-in versions are used internally by GCC's libraries
+to implement exception handling on some targets. You should use the
+standard C library functions declared in @code{<setjmp.h>} in user code
+instead of the builtins.
-Recall that a compound statement is a sequence of statements surrounded
-by braces; in this construct, parentheses go around the braces. For
-example:
+The built-in versions of these functions use GCC's normal
+mechanisms to save and restore registers using the stack on function
+entry and exit. The jump buffer argument @var{buf} holds only the
+information needed to restore the stack frame, rather than the entire
+set of saved register values.
+
+An important caveat is that GCC arranges to save and restore only
+those registers known to the specific architecture variant being
+compiled for. This can make @code{__builtin_setjmp} and
+@code{__builtin_longjmp} more efficient than their library
+counterparts in some cases, but it can also cause incorrect and
+mysterious behavior when mixing with code that uses the full register
+set.
+
+You should declare the jump buffer argument @var{buf} to the
+built-in functions as:
@smallexample
-(@{ int y = foo (); int z;
- if (y > 0) z = y;
- else z = - y;
- z; @})
+#include <stdint.h>
+intptr_t @var{buf}[5];
@end smallexample
-@noindent
-is a valid (though slightly more complex than necessary) expression
-for the absolute value of @code{foo ()}.
+@defbuiltin{{int} __builtin_setjmp (intptr_t *@var{buf})}
+This function saves the current stack context in @var{buf}.
+@code{__builtin_setjmp} returns 0 when returning directly,
+and 1 when returning from @code{__builtin_longjmp} using the same
+@var{buf}.
+@enddefbuiltin
-The last thing in the compound statement should be an expression
-followed by a semicolon; the value of this subexpression serves as the
-value of the entire construct. (If you use some other kind of statement
-last within the braces, the construct has type @code{void}, and thus
-effectively no value.)
+@defbuiltin{{void} __builtin_longjmp (intptr_t *@var{buf}, int @var{val})}
+This function restores the stack context in @var{buf},
+saved by a previous call to @code{__builtin_setjmp}. After
+@code{__builtin_longjmp} is finished, the program resumes execution as
+if the matching @code{__builtin_setjmp} returns the value @var{val},
+which must be 1.
-This feature is especially useful in making macro definitions ``safe'' (so
-that they evaluate each operand exactly once). For example, the
-``maximum'' function is commonly defined as a macro in standard C as
-follows:
+Because @code{__builtin_longjmp} depends on the function return
+mechanism to restore the stack context, it cannot be called
+from the same function calling @code{__builtin_setjmp} to
+initialize @var{buf}. It can only be called from a function called
+(directly or indirectly) from the function calling @code{__builtin_setjmp}.
+@enddefbuiltin
-@smallexample
-#define max(a,b) ((a) > (b) ? (a) : (b))
-@end smallexample
+@node Constructing Calls
+@section Constructing Function Calls
+@cindex constructing calls
+@cindex forwarding calls
-@noindent
-@cindex side effects, macro argument
-But this definition computes either @var{a} or @var{b} twice, with bad
-results if the operand has side effects. In GNU C, if you know the
-type of the operands (here taken as @code{int}), you can avoid this
-problem by defining the macro as follows:
+Using the built-in functions described below, you can record
+the arguments a function received, and call another function
+with the same arguments, without knowing the number or types
+of the arguments.
-@smallexample
-#define maxint(a,b) \
- (@{int _a = (a), _b = (b); _a > _b ? _a : _b; @})
-@end smallexample
+You can also record the return value of that function call,
+and later return that value, without knowing what data type
+the function tried to return (as long as your caller expects
+that data type).
-Note that introducing variable declarations (as we do in @code{maxint}) can
-cause variable shadowing, so while this example using the @code{max} macro
-produces correct results:
-@smallexample
-int _a = 1, _b = 2, c;
-c = max (_a, _b);
-@end smallexample
-@noindent
-this example using maxint will not:
-@smallexample
-int _a = 1, _b = 2, c;
-c = maxint (_a, _b);
-@end smallexample
+However, these built-in functions may interact badly with some
+sophisticated features or other extensions of the language. It
+is, therefore, not recommended to use them outside very simple
+functions acting as mere forwarders for their arguments.
-This problem may for instance occur when we use this pattern recursively, like
-so:
+@defbuiltin{{void *} __builtin_apply_args ()}
+This built-in function returns a pointer to data
+describing how to perform a call with the same arguments as are passed
+to the current function.
-@smallexample
-#define maxint3(a, b, c) \
- (@{int _a = (a), _b = (b), _c = (c); maxint (maxint (_a, _b), _c); @})
-@end smallexample
+The function saves the arg pointer register, structure value address,
+and all registers that might be used to pass arguments to a function
+into a block of memory allocated on the stack. Then it returns the
+address of that block.
+@enddefbuiltin
-Embedded statements are not allowed in constant expressions, such as
-the value of an enumeration constant, the width of a bit-field, or
-the initial value of a static variable.
+@defbuiltin{{void *} __builtin_apply (void (*@var{function})(), void *@var{arguments}, size_t @var{size})}
+This built-in function invokes @var{function}
+with a copy of the parameters described by @var{arguments}
+and @var{size}.
-If you don't know the type of the operand, you can still do this, but you
-must use @code{typeof} or @code{__auto_type} (@pxref{Typeof}).
+The value of @var{arguments} should be the value returned by
+@code{__builtin_apply_args}. The argument @var{size} specifies the size
+of the stack argument data, in bytes.
-In G++, the result value of a statement expression undergoes array and
-function pointer decay, and is returned by value to the enclosing
-expression. For instance, if @code{A} is a class, then
+This function returns a pointer to data describing
+how to return whatever value is returned by @var{function}. The data
+is saved in a block of memory allocated on the stack.
-@smallexample
- A a;
+It is not always simple to compute the proper value for @var{size}. The
+value is used by @code{__builtin_apply} to compute the amount of data
+that should be pushed on the stack and copied from the incoming argument
+area.
+@enddefbuiltin
- (@{a;@}).Foo ()
+@defbuiltin{{void} __builtin_return (void *@var{result})}
+This built-in function returns the value described by @var{result} from
+the containing function. You should specify, for @var{result}, a value
+returned by @code{__builtin_apply}.
+@enddefbuiltin
+
+@defbuiltin{{} __builtin_va_arg_pack ()}
+This built-in function represents all anonymous arguments of an inline
+function. It can be used only in inline functions that are always
+inlined, never compiled as a separate function, such as those using
+@code{__attribute__ ((__always_inline__))} or
+@code{__attribute__ ((__gnu_inline__))} extern inline functions.
+It must be only passed as last argument to some other function
+with variable arguments. This is useful for writing small wrapper
+inlines for variable argument functions, when using preprocessor
+macros is undesirable. For example:
+@smallexample
+extern int myprintf (FILE *f, const char *format, ...);
+extern inline __attribute__ ((__gnu_inline__)) int
+myprintf (FILE *f, const char *format, ...)
+@{
+ int r = fprintf (f, "myprintf: ");
+ if (r < 0)
+ return r;
+ int s = fprintf (f, format, __builtin_va_arg_pack ());
+ if (s < 0)
+ return s;
+ return r + s;
+@}
@end smallexample
+@enddefbuiltin
-@noindent
-constructs a temporary @code{A} object to hold the result of the
-statement expression, and that is used to invoke @code{Foo}.
-Therefore the @code{this} pointer observed by @code{Foo} is not the
-address of @code{a}.
+@defbuiltin{int __builtin_va_arg_pack_len ()}
+This built-in function returns the number of anonymous arguments of
+an inline function. It can be used only in inline functions that
+are always inlined, never compiled as a separate function, such
+as those using @code{__attribute__ ((__always_inline__))} or
+@code{__attribute__ ((__gnu_inline__))} extern inline functions.
+For example following does link- or run-time checking of open
+arguments for optimized code:
+@smallexample
+#ifdef __OPTIMIZE__
+extern inline __attribute__((__gnu_inline__)) int
+myopen (const char *path, int oflag, ...)
+@{
+ if (__builtin_va_arg_pack_len () > 1)
+ warn_open_too_many_arguments ();
-In a statement expression, any temporaries created within a statement
-are destroyed at that statement's end. This makes statement
-expressions inside macros slightly different from function calls. In
-the latter case temporaries introduced during argument evaluation are
-destroyed at the end of the statement that includes the function
-call. In the statement expression case they are destroyed during
-the statement expression. For instance,
+ if (__builtin_constant_p (oflag))
+ @{
+ if ((oflag & O_CREAT) != 0 && __builtin_va_arg_pack_len () < 1)
+ @{
+ warn_open_missing_mode ();
+ return __open_2 (path, oflag);
+ @}
+ return open (path, oflag, __builtin_va_arg_pack ());
+ @}
-@smallexample
-#define macro(a) (@{__typeof__(a) b = (a); b + 3; @})
-template<typename T> T function(T a) @{ T b = a; return b + 3; @}
+ if (__builtin_va_arg_pack_len () < 1)
+ return __open_2 (path, oflag);
-void foo ()
-@{
- macro (X ());
- function (X ());
+ return open (path, oflag, __builtin_va_arg_pack ());
@}
+#endif
@end smallexample
+@enddefbuiltin
-@noindent
-has different places where temporaries are destroyed. For the
-@code{macro} case, the temporary @code{X} is destroyed just after
-the initialization of @code{b}. In the @code{function} case that
-temporary is destroyed when the function returns.
-
-These considerations mean that it is probably a bad idea to use
-statement expressions of this form in header files that are designed to
-work with C++. (Note that some versions of the GNU C Library contained
-header files using statement expressions that lead to precisely this
-bug.)
-
-Jumping into a statement expression with @code{goto} or using a
-@code{switch} statement outside the statement expression with a
-@code{case} or @code{default} label inside the statement expression is
-not permitted. Jumping into a statement expression with a computed
-@code{goto} (@pxref{Labels as Values}) has undefined behavior.
-Jumping out of a statement expression is permitted, but if the
-statement expression is part of a larger expression then it is
-unspecified which other subexpressions of that expression have been
-evaluated except where the language definition requires certain
-subexpressions to be evaluated before or after the statement
-expression. A @code{break} or @code{continue} statement inside of
-a statement expression used in @code{while}, @code{do} or @code{for}
-loop or @code{switch} statement condition
-or @code{for} statement init or increment expressions jumps to an
-outer loop or @code{switch} statement if any (otherwise it is an error),
-rather than to the loop or @code{switch} statement in whose condition
-or init or increment expression it appears.
-In any case, as with a function call, the evaluation of a
-statement expression is not interleaved with the evaluation of other
-parts of the containing expression. For example,
+@node Additional Numeric Types
+@section Additional Numeric Types
-@smallexample
- foo (), ((@{ bar1 (); goto a; 0; @}) + bar2 ()), baz();
-@end smallexample
+GCC supports additional numeric types, including larger integer types,
+integer and floating-point complex types,
+additional floating-point sizes and formats, decimal floating types,
+and fixed-point types.
-@noindent
-calls @code{foo} and @code{bar1} and does not call @code{baz} but
-may or may not call @code{bar2}. If @code{bar2} is called, it is
-called after @code{foo} and before @code{bar1}.
+@menu
+* __int128:: 128-bit integers---@code{__int128}.
+* Long Long:: Double-word integers---@code{long long int}.
+* Complex:: Data types for complex numbers.
+* Floating Types:: Additional Floating Types.
+* Half-Precision:: Half-Precision Floating Point.
+* Decimal Float:: Decimal Floating Types.
+* Fixed-Point:: Fixed-Point Types.
+@end menu
-@node Local Labels
-@section Locally Declared Labels
-@cindex local labels
-@cindex macros, local labels
+@node __int128
+@subsection 128-bit Integers
+@cindex @code{__int128} data types
-GCC allows you to declare @dfn{local labels} in any nested block
-scope. A local label is just like an ordinary label, but you can
-only reference it (with a @code{goto} statement, or by taking its
-address) within the block in which it is declared.
+As an extension the integer scalar type @code{__int128} is supported for
+targets which have an integer mode wide enough to hold 128 bits.
+Simply write @code{__int128} for a signed 128-bit integer, or
+@code{unsigned __int128} for an unsigned 128-bit integer. There is no
+support in GCC for expressing an integer constant of type @code{__int128}
+for targets with @code{long long} integer less than 128 bits wide.
-A local label declaration looks like this:
+@node Long Long
+@subsection Double-Word Integers
+@cindex @code{long long} data types
+@cindex double-word arithmetic
+@cindex multiprecision arithmetic
+@cindex @code{LL} integer suffix
+@cindex @code{ULL} integer suffix
-@smallexample
-__label__ @var{label};
-@end smallexample
+ISO C99 and ISO C++11 support data types for integers that are at least
+64 bits wide, and as an extension GCC supports them in C90 and C++98 modes.
+Simply write @code{long long int} for a signed integer, or
+@code{unsigned long long int} for an unsigned integer. To make an
+integer constant of type @code{long long int}, add the suffix @samp{LL}
+to the integer. To make an integer constant of type @code{unsigned long
+long int}, add the suffix @samp{ULL} to the integer.
-@noindent
-or
+You can use these types in arithmetic like any other integer types.
+Addition, subtraction, and bitwise boolean operations on these types
+are open-coded on all types of machines. Multiplication is open-coded
+if the machine supports a fullword-to-doubleword widening multiply
+instruction. Division and shifts are open-coded only on machines that
+provide special support. The operations that are not open-coded use
+special library routines that come with GCC@.
-@smallexample
-__label__ @var{label1}, @var{label2}, /* @r{@dots{}} */;
-@end smallexample
+There may be pitfalls when you use @code{long long} types for function
+arguments without function prototypes. If a function
+expects type @code{int} for its argument, and you pass a value of type
+@code{long long int}, confusion results because the caller and the
+subroutine disagree about the number of bytes for the argument.
+Likewise, if the function expects @code{long long int} and you pass
+@code{int}. The best way to avoid such problems is to use prototypes.
-Local label declarations must come at the beginning of the block,
-before any ordinary declarations or statements.
+@node Complex
+@subsection Complex Numbers
+@cindex complex numbers
+@cindex @code{_Complex} keyword
+@cindex @code{__complex__} keyword
-The label declaration defines the label @emph{name}, but does not define
-the label itself. You must do this in the usual way, with
-@code{@var{label}:}, within the statements of the statement expression.
+ISO C99 supports complex floating data types, and as an extension GCC
+supports them in C90 mode and in C++. GCC also supports complex integer data
+types which are not part of ISO C99. You can declare complex types
+using the keyword @code{_Complex}. As an extension, the older GNU
+keyword @code{__complex__} is also supported.
-The local label feature is useful for complex macros. If a macro
-contains nested loops, a @code{goto} can be useful for breaking out of
-them. However, an ordinary label whose scope is the whole function
-cannot be used: if the macro can be expanded several times in one
-function, the label is multiply defined in that function. A
-local label avoids this problem. For example:
+For example, @samp{_Complex double x;} declares @code{x} as a
+variable whose real part and imaginary part are both of type
+@code{double}. @samp{_Complex short int y;} declares @code{y} to
+have real and imaginary parts of type @code{short int}; this is not
+likely to be useful, but it shows that the set of complex types is
+complete.
-@smallexample
-#define SEARCH(value, array, target) \
-do @{ \
- __label__ found; \
- typeof (target) _SEARCH_target = (target); \
- typeof (*(array)) *_SEARCH_array = (array); \
- int i, j; \
- int value; \
- for (i = 0; i < max; i++) \
- for (j = 0; j < max; j++) \
- if (_SEARCH_array[i][j] == _SEARCH_target) \
- @{ (value) = i; goto found; @} \
- (value) = -1; \
- found:; \
-@} while (0)
-@end smallexample
+To write a constant with a complex data type, use the suffix @samp{i},
+@samp{I}, @samp{j} or @samp{J} (any one; they are equivalent). For
+example, @code{2.5fi} has type @code{_Complex float} and @code{3i} has type
+@code{_Complex int}. Such a constant always has a pure imaginary
+value, but you can form any complex value you like by adding one to a
+real constant. This is part of ISO C2Y and for older C revisions
+a GNU extension. If you have an ISO C99 conforming C library
+(such as the GNU C Library), and want to construct complex
+constants of floating type when using standard versions before ISO C2Y,
+you should include @code{<complex.h>} and use the macros @code{I} or
+@code{_Complex_I} instead.
-This could also be written using a statement expression:
+For C++ if @code{-fext-numeric-literals} option is enabled, it is also
+a GNU extension, otherwise it is handled like any other C++ user-defined
+literal. The ISO C++14 library also defines the @samp{i} suffix, so C++14
+code that includes the @samp{<complex>} header cannot use @samp{i} for the
+GNU extension. The @samp{I}, @samp{j} or @samp{J} suffixes still have
+the GNU meaning.
-@smallexample
-#define SEARCH(array, target) \
-(@{ \
- __label__ found; \
- typeof (target) _SEARCH_target = (target); \
- typeof (*(array)) *_SEARCH_array = (array); \
- int i, j; \
- int value; \
- for (i = 0; i < max; i++) \
- for (j = 0; j < max; j++) \
- if (_SEARCH_array[i][j] == _SEARCH_target) \
- @{ value = i; goto found; @} \
- value = -1; \
- found: \
- value; \
-@})
-@end smallexample
+GCC handles both implicit and explicit casts between the
+@code{_Complex} types with different scalar base types by casting both
+the real and imaginary parts to the base type of the result.
+GCC also handles implicit and explicit casts from a scalar type to a
+@code{_Complex} type, by giving the imaginary part a zero value.
-Local label declarations also make the labels they declare visible to
-nested functions, if there are any. @xref{Nested Functions}, for details.
+The C front end can handle implicit and explicit casts from a
+@code{_Complex} type to a scalar type, which uses the value of the
+real part and ignores the imaginary part. In C++ code, this cast is
+considered ill-formed and G++ diagnoses it as an error.
-@node Labels as Values
-@section Labels as Values
-@cindex labels as values
-@cindex computed gotos
-@cindex goto with computed label
-@cindex address of a label
+@cindex @code{__real__} keyword
+@cindex @code{__imag__} keyword
-You can get the address of a label defined in the current function
-(or a containing function) with the unary operator @samp{&&}. The
-value has type @code{void *}. This value is a constant and can be used
-wherever a constant of that type is valid. For example:
+GCC has a few extensions which can be used to extract the real
+and the imaginary part of the complex-valued expression. Note
+these expressions are lvalues if the @var{exp} is an lvalue.
+These expressions operands have the type of a complex type
+which might get promoted to a complex type from a scalar type.
+E.g. @code{__real__ (int)@var{x}} is the same as casting to
+@code{_Complex int} before @code{__real__} is done.
-@smallexample
-void *ptr;
-/* @r{@dots{}} */
-ptr = &&foo;
-@end smallexample
+@multitable @columnfractions .4 .6
+@headitem Expression @tab Description
+@item @code{__real__ @var{exp}}
+@tab Extract the real part of @var{exp}.
+@item @code{__imag__ @var{exp}}
+@tab Extract the imaginary part of @var{exp}.
+@end multitable
-To use these values, you need to be able to jump to one. This is done
-with the computed goto statement@footnote{The analogous feature in
-Fortran is called an assigned goto, but that name seems inappropriate in
-C, where one can do more than simply store label addresses in label
-variables.}, @code{goto *@var{exp};}. For example,
+For values of floating-point type, you should use the ISO C99
+functions, declared in @code{<complex.h>} and also provided as
+built-in functions by GCC@.
-@smallexample
-goto *ptr;
-@end smallexample
+@multitable @columnfractions .4 .2 .2 .2
+@headitem Expression @tab float @tab double @tab long double
+@item @code{__real__ @var{exp}}
+@tab @code{crealf} @tab @code{creal} @tab @code{creall}
+@item @code{__imag__ @var{exp}}
+@tab @code{cimagf} @tab @code{cimag} @tab @code{cimagl}
+@end multitable
-@noindent
-Any expression of type @code{void *} is allowed.
+@cindex complex conjugation
+The operator @samp{~} performs complex conjugation when used on a value
+with a complex type. This is a GNU extension; for values of
+floating type, you should use the ISO C99 functions @code{conjf},
+@code{conj} and @code{conjl}, declared in @code{<complex.h>} and also
+provided as built-in functions by GCC@. Note unlike the @code{__real__}
+and @code{__imag__} operators, this operator does not do an implicit cast
+to the complex type because the @samp{~} is already a normal operator.
-One way of using these constants is in initializing a static array that
-serves as a jump table:
-
-@smallexample
-static void *array[] = @{ &&foo, &&bar, &&hack @};
-@end smallexample
-
-@noindent
-Then you can select a label with indexing, like this:
-
-@smallexample
-goto *array[i];
-@end smallexample
+GCC can allocate complex automatic variables in a noncontiguous
+fashion; it's even possible for the real part to be in a register while
+the imaginary part is on the stack (or vice versa). Only the DWARF
+debug info format can represent this, so use of DWARF is recommended.
+If you are using the stabs debug info format, GCC describes a noncontiguous
+complex variable as if it were two separate variables of noncomplex type.
+If the variable's actual name is @code{foo}, the two fictitious
+variables are named @code{foo$real} and @code{foo$imag}. You can
+examine and set these two fictitious variables with your debugger.
-@noindent
-Note that this does not check whether the subscript is in bounds---array
-indexing in C never does that.
+@defbuiltin{@var{type} __builtin_complex (@var{real}, @var{imag})}
-Such an array of label values serves a purpose much like that of the
-@code{switch} statement. The @code{switch} statement is cleaner, so
-use that rather than an array unless the problem does not fit a
-@code{switch} statement very well.
+The built-in function @code{__builtin_complex} is provided for use in
+implementing the ISO C11 macros @code{CMPLXF}, @code{CMPLX} and
+@code{CMPLXL}. @var{real} and @var{imag} must have the same type, a
+real binary floating-point type, and the result has the corresponding
+complex type with real and imaginary parts @var{real} and @var{imag}.
+Unlike @samp{@var{real} + I * @var{imag}}, this works even when
+infinities, NaNs and negative zeros are involved.
-Another use of label values is in an interpreter for threaded code.
-The labels within the interpreter function can be stored in the
-threaded code for super-fast dispatching.
+@enddefbuiltin
-You may not use this mechanism to jump to code in a different function.
-If you do that, totally unpredictable things happen. The best way to
-avoid this is to store the label address only in automatic variables and
-never pass it as an argument.
+@node Floating Types
+@subsection Additional Floating Types
+@cindex additional floating types
+@cindex @code{_Float@var{n}} data types
+@cindex @code{_Float@var{n}x} data types
+@cindex @code{__float80} data type
+@cindex @code{__float128} data type
+@cindex @code{__ibm128} data type
+@cindex @code{w} floating point suffix
+@cindex @code{q} floating point suffix
+@cindex @code{W} floating point suffix
+@cindex @code{Q} floating point suffix
-An alternate way to write the above example is
+ISO/IEC TS 18661-3:2015 defines C support for additional floating
+types @code{_Float@var{n}} and @code{_Float@var{n}x}, and GCC supports
+these type names; the set of types supported depends on the target
+architecture.
+Constants with these types use suffixes @code{f@var{n}} or
+@code{F@var{n}} and @code{f@var{n}x} or @code{F@var{n}x}. These type
+names can be used together with @code{_Complex} to declare complex
+types.
-@smallexample
-static const int array[] = @{ &&foo - &&foo, &&bar - &&foo,
- &&hack - &&foo @};
-goto *(&&foo + array[i]);
-@end smallexample
+As an extension, GNU C and GNU C++ support additional floating
+types, which are not supported by all targets.
+@itemize @bullet
+@item @code{__float128} is available on i386, x86_64, IA-64, LoongArch
+and hppa HP-UX, as well as on PowerPC GNU/Linux targets that enable
+the vector scalar (VSX) instruction set. @code{__float128} supports
+the 128-bit floating type. On i386, x86_64, PowerPC, LoongArch and IA-64,
+other than HP-UX, @code{__float128} is an alias for @code{_Float128}.
+On hppa and IA-64 HP-UX, @code{__float128} is an alias for @code{long
+double}.
-@noindent
-This is more friendly to code living in shared libraries, as it reduces
-the number of dynamic relocations that are needed, and by consequence,
-allows the data to be read-only.
-This alternative with label differences is not supported for the AVR target,
-please use the first approach for AVR programs.
+@item @code{__float80} is available on the i386, x86_64, and IA-64
+targets, and supports the 80-bit (@code{XFmode}) floating type. It is
+an alias for the type name @code{_Float64x} on these targets.
-The @code{&&foo} expressions for the same label might have different
-values if the containing function is inlined or cloned. If a program
-relies on them being always the same,
-@code{__attribute__((__noinline__,__noclone__))} should be used to
-prevent inlining and cloning. If @code{&&foo} is used in a static
-variable initializer, inlining and cloning is forbidden.
+@item @code{__ibm128} is available on PowerPC targets, and provides
+access to the IBM extended double format which is the current format
+used for @code{long double}. When @code{long double} transitions to
+@code{__float128} on PowerPC in the future, @code{__ibm128} will remain
+for use in conversions between the two types.
+@end itemize
-Unlike a normal goto, in GNU C++ a computed goto will not call
-destructors for objects that go out of scope.
+Support for these additional types includes the arithmetic operators:
+add, subtract, multiply, divide; unary arithmetic operators;
+relational operators; equality operators; and conversions to and from
+integer and other floating types. Use a suffix @samp{w} or @samp{W}
+in a literal constant of type @code{__float80} or type
+@code{__ibm128}. Use a suffix @samp{q} or @samp{Q} for @code{__float128}.
-@node Nested Functions
-@section Nested Functions
-@cindex nested functions
-@cindex downward funargs
-@cindex thunks
+In order to use @code{_Float128}, @code{__float128}, and @code{__ibm128}
+on PowerPC Linux systems, you must use the @option{-mfloat128} option. It is
+expected in future versions of GCC that @code{_Float128} and @code{__float128}
+will be enabled automatically.
-A @dfn{nested function} is a function defined inside another function.
-Nested functions are supported as an extension in GNU C, but are not
-supported by GNU C++.
+The @code{_Float128} type is supported on all systems where
+@code{__float128} is supported or where @code{long double} has the
+IEEE binary128 format. The @code{_Float64x} type is supported on all
+systems where @code{__float128} is supported. The @code{_Float32}
+type is supported on all systems supporting IEEE binary32; the
+@code{_Float64} and @code{_Float32x} types are supported on all systems
+supporting IEEE binary64. The @code{_Float16} type is supported on AArch64
+systems by default, on ARM systems when the IEEE format for 16-bit
+floating-point types is selected with @option{-mfp16-format=ieee} and,
+for both C and C++, on x86 systems with SSE2 enabled. GCC does not currently
+support @code{_Float128x} on any systems.
-The nested function's name is local to the block where it is defined.
-For example, here we define a nested function named @code{square}, and
-call it twice:
+On the i386, x86_64, IA-64, and HP-UX targets, you can declare complex
+types using the corresponding internal complex type, @code{XCmode} for
+@code{__float80} type and @code{TCmode} for @code{__float128} type:
@smallexample
-@group
-foo (double a, double b)
-@{
- double square (double z) @{ return z * z; @}
-
- return square (a) + square (b);
-@}
-@end group
+typedef _Complex float __attribute__((mode(TC))) _Complex128;
+typedef _Complex float __attribute__((mode(XC))) _Complex80;
@end smallexample
-The nested function can access all the variables of the containing
-function that are visible at the point of its definition. This is
-called @dfn{lexical scoping}. For example, here we show a nested
-function which uses an inherited variable named @code{offset}:
+On the PowerPC Linux VSX targets, you can declare complex types using
+the corresponding internal complex type, @code{KCmode} for
+@code{__float128} type and @code{ICmode} for @code{__ibm128} type:
@smallexample
-@group
-bar (int *array, int offset, int size)
-@{
- int access (int *array, int index)
- @{ return array[index + offset]; @}
- int i;
- /* @r{@dots{}} */
- for (i = 0; i < size; i++)
- /* @r{@dots{}} */ access (array, i) /* @r{@dots{}} */
-@}
-@end group
+typedef _Complex float __attribute__((mode(KC))) _Complex_float128;
+typedef _Complex float __attribute__((mode(IC))) _Complex_ibm128;
@end smallexample
-Nested function definitions are permitted within functions in the places
-where variable definitions are allowed; that is, in any block, mixed
-with the other declarations and statements in the block.
+@node Half-Precision
+@subsection Half-Precision Floating Point
+@cindex half-precision floating point
+@cindex @code{__fp16} data type
+@cindex @code{__Float16} data type
-It is possible to call the nested function from outside the scope of its
-name by storing its address or passing the address to another function:
+On ARM and AArch64 targets, GCC supports half-precision (16-bit) floating
+point via the @code{__fp16} type defined in the ARM C Language Extensions.
+On ARM systems, you must enable this type explicitly with the
+@option{-mfp16-format} command-line option in order to use it.
+On x86 targets with SSE2 enabled, GCC supports half-precision (16-bit)
+floating point via the @code{_Float16} type. For C++, x86 provides a builtin
+type named @code{_Float16} which contains same data format as C.
-@smallexample
-hack (int *array, int size)
-@{
- void store (int index, int value)
- @{ array[index] = value; @}
+ARM targets support two incompatible representations for half-precision
+floating-point values. You must choose one of the representations and
+use it consistently in your program.
- intermediate (store, size);
-@}
-@end smallexample
+Specifying @option{-mfp16-format=ieee} selects the IEEE 754-2008 format.
+This format can represent normalized values in the range of @math{2^{-14}} to 65504.
+There are 11 bits of significand precision, approximately 3
+decimal digits.
-Here, the function @code{intermediate} receives the address of
-@code{store} as an argument. If @code{intermediate} calls @code{store},
-the arguments given to @code{store} are used to store into @code{array}.
-But this technique works only so long as the containing function
-(@code{hack}, in this example) does not exit.
+Specifying @option{-mfp16-format=alternative} selects the ARM
+alternative format. This representation is similar to the IEEE
+format, but does not support infinities or NaNs. Instead, the range
+of exponents is extended, so that this format can represent normalized
+values in the range of @math{2^{-14}} to 131008.
-If you try to call the nested function through its address after the
-containing function exits, all hell breaks loose. If you try
-to call it after a containing scope level exits, and if it refers
-to some of the variables that are no longer in scope, you may be lucky,
-but it's not wise to take the risk. If, however, the nested function
-does not refer to anything that has gone out of scope, you should be
-safe.
+The GCC port for AArch64 only supports the IEEE 754-2008 format, and does
+not require use of the @option{-mfp16-format} command-line option.
-GCC implements taking the address of a nested function using a technique
-called @dfn{trampolines}. This technique was described in
-@cite{Lexical Closures for C++} (Thomas M. Breuel, USENIX
-C++ Conference Proceedings, October 17-21, 1988).
+The @code{__fp16} type may only be used as an argument to intrinsics defined
+in @code{<arm_fp16.h>}, or as a storage format. For purposes of
+arithmetic and other operations, @code{__fp16} values in C or C++
+expressions are automatically promoted to @code{float}.
-A nested function can jump to a label inherited from a containing
-function, provided the label is explicitly declared in the containing
-function (@pxref{Local Labels}). Such a jump returns instantly to the
-containing function, exiting the nested function that did the
-@code{goto} and any intermediate functions as well. Here is an example:
+The ARM target provides hardware support for conversions between
+@code{__fp16} and @code{float} values
+as an extension to VFP and NEON (Advanced SIMD), and from ARMv8-A provides
+hardware support for conversions between @code{__fp16} and @code{double}
+values. GCC generates code using these hardware instructions if you
+compile with options to select an FPU that provides them;
+for example, @option{-mfpu=neon-fp16 -mfloat-abi=softfp},
+in addition to the @option{-mfp16-format} option to select
+a half-precision format.
-@smallexample
-@group
-bar (int *array, int offset, int size)
-@{
- __label__ failure;
- int access (int *array, int index)
- @{
- if (index > size)
- goto failure;
- return array[index + offset];
- @}
- int i;
- /* @r{@dots{}} */
- for (i = 0; i < size; i++)
- /* @r{@dots{}} */ access (array, i) /* @r{@dots{}} */
- /* @r{@dots{}} */
- return 0;
-
- /* @r{Control comes here from @code{access}
- if it detects an error.} */
- failure:
- return -1;
-@}
-@end group
-@end smallexample
+Language-level support for the @code{__fp16} data type is
+independent of whether GCC generates code using hardware floating-point
+instructions. In cases where hardware support is not specified, GCC
+implements conversions between @code{__fp16} and other types as library
+calls.
-A nested function always has no linkage. Declaring one with
-@code{extern} or @code{static} is erroneous. If you need to declare the nested function
-before its definition, use @code{auto} (which is otherwise meaningless
-for function declarations).
+It is recommended that portable code use the @code{_Float16} type defined
+by ISO/IEC TS 18661-3:2015. @xref{Floating Types}.
-@smallexample
-bar (int *array, int offset, int size)
-@{
- __label__ failure;
- auto int access (int *, int);
- /* @r{@dots{}} */
- int access (int *array, int index)
- @{
- if (index > size)
- goto failure;
- return array[index + offset];
- @}
- /* @r{@dots{}} */
-@}
-@end smallexample
+On x86 targets with SSE2 enabled, without @option{-mavx512fp16},
+all operations will be emulated by software emulation and the @code{float}
+instructions. The default behavior for @code{FLT_EVAL_METHOD} is to keep the
+intermediate result of the operation as 32-bit precision. This may lead to
+inconsistent behavior between software emulation and AVX512-FP16 instructions.
+Using @option{-fexcess-precision=16} will force round back after each operation.
-@node Nonlocal Gotos
-@section Nonlocal Gotos
-@cindex nonlocal gotos
+Using @option{-mavx512fp16} will generate AVX512-FP16 instructions instead of
+software emulation. The default behavior of @code{FLT_EVAL_METHOD} is to round
+after each operation. The same is true with @option{-fexcess-precision=standard}
+and @option{-mfpmath=sse}. If there is no @option{-mfpmath=sse},
+@option{-fexcess-precision=standard} alone does the same thing as before,
+It is useful for code that does not have @code{_Float16} and runs on the x87
+FPU.
-GCC provides the built-in functions @code{__builtin_setjmp} and
-@code{__builtin_longjmp} which are similar to, but not interchangeable
-with, the C library functions @code{setjmp} and @code{longjmp}.
-The built-in versions are used internally by GCC's libraries
-to implement exception handling on some targets. You should use the
-standard C library functions declared in @code{<setjmp.h>} in user code
-instead of the builtins.
+@node Decimal Float
+@subsection Decimal Floating Types
+@cindex decimal floating types
+@cindex @code{_Decimal32} data type
+@cindex @code{_Decimal64} data type
+@cindex @code{_Decimal128} data type
+@cindex @code{df} integer suffix
+@cindex @code{dd} integer suffix
+@cindex @code{dl} integer suffix
+@cindex @code{DF} integer suffix
+@cindex @code{DD} integer suffix
+@cindex @code{DL} integer suffix
-The built-in versions of these functions use GCC's normal
-mechanisms to save and restore registers using the stack on function
-entry and exit. The jump buffer argument @var{buf} holds only the
-information needed to restore the stack frame, rather than the entire
-set of saved register values.
+As an extension, GNU C supports decimal floating types as
+defined in the N1312 draft of ISO/IEC WDTR24732. Support for decimal
+floating types in GCC will evolve as the draft technical report changes.
+Calling conventions for any target might also change. Not all targets
+support decimal floating types.
-An important caveat is that GCC arranges to save and restore only
-those registers known to the specific architecture variant being
-compiled for. This can make @code{__builtin_setjmp} and
-@code{__builtin_longjmp} more efficient than their library
-counterparts in some cases, but it can also cause incorrect and
-mysterious behavior when mixing with code that uses the full register
-set.
+The decimal floating types are @code{_Decimal32}, @code{_Decimal64}, and
+@code{_Decimal128}. They use a radix of ten, unlike the floating types
+@code{float}, @code{double}, and @code{long double} whose radix is not
+specified by the C standard but is usually two.
-You should declare the jump buffer argument @var{buf} to the
-built-in functions as:
+Support for decimal floating types includes the arithmetic operators
+add, subtract, multiply, divide; unary arithmetic operators;
+relational operators; equality operators; and conversions to and from
+integer and other floating types. Use a suffix @samp{df} or
+@samp{DF} in a literal constant of type @code{_Decimal32}, @samp{dd}
+or @samp{DD} for @code{_Decimal64}, and @samp{dl} or @samp{DL} for
+@code{_Decimal128}.
-@smallexample
-#include <stdint.h>
-intptr_t @var{buf}[5];
-@end smallexample
+GCC support of decimal float as specified by the draft technical report
+is incomplete:
-@defbuiltin{{int} __builtin_setjmp (intptr_t *@var{buf})}
-This function saves the current stack context in @var{buf}.
-@code{__builtin_setjmp} returns 0 when returning directly,
-and 1 when returning from @code{__builtin_longjmp} using the same
-@var{buf}.
-@enddefbuiltin
+@itemize @bullet
+@item
+When the value of a decimal floating type cannot be represented in the
+integer type to which it is being converted, the result is undefined
+rather than the result value specified by the draft technical report.
-@defbuiltin{{void} __builtin_longjmp (intptr_t *@var{buf}, int @var{val})}
-This function restores the stack context in @var{buf},
-saved by a previous call to @code{__builtin_setjmp}. After
-@code{__builtin_longjmp} is finished, the program resumes execution as
-if the matching @code{__builtin_setjmp} returns the value @var{val},
-which must be 1.
+@item
+GCC does not provide the C library functionality associated with
+@file{math.h}, @file{fenv.h}, @file{stdio.h}, @file{stdlib.h}, and
+@file{wchar.h}, which must come from a separate C library implementation.
+Because of this the GNU C compiler does not define macro
+@code{__STDC_DEC_FP__} to indicate that the implementation conforms to
+the technical report.
+@end itemize
-Because @code{__builtin_longjmp} depends on the function return
-mechanism to restore the stack context, it cannot be called
-from the same function calling @code{__builtin_setjmp} to
-initialize @var{buf}. It can only be called from a function called
-(directly or indirectly) from the function calling @code{__builtin_setjmp}.
-@enddefbuiltin
+Types @code{_Decimal32}, @code{_Decimal64}, and @code{_Decimal128}
+are supported by the DWARF debug information format.
-@node Constructing Calls
-@section Constructing Function Calls
-@cindex constructing calls
-@cindex forwarding calls
+@node Fixed-Point
+@subsection Fixed-Point Types
+@cindex fixed-point types
+@cindex @code{_Fract} data type
+@cindex @code{_Accum} data type
+@cindex @code{_Sat} data type
+@cindex @code{hr} fixed-suffix
+@cindex @code{r} fixed-suffix
+@cindex @code{lr} fixed-suffix
+@cindex @code{llr} fixed-suffix
+@cindex @code{uhr} fixed-suffix
+@cindex @code{ur} fixed-suffix
+@cindex @code{ulr} fixed-suffix
+@cindex @code{ullr} fixed-suffix
+@cindex @code{hk} fixed-suffix
+@cindex @code{k} fixed-suffix
+@cindex @code{lk} fixed-suffix
+@cindex @code{llk} fixed-suffix
+@cindex @code{uhk} fixed-suffix
+@cindex @code{uk} fixed-suffix
+@cindex @code{ulk} fixed-suffix
+@cindex @code{ullk} fixed-suffix
+@cindex @code{HR} fixed-suffix
+@cindex @code{R} fixed-suffix
+@cindex @code{LR} fixed-suffix
+@cindex @code{LLR} fixed-suffix
+@cindex @code{UHR} fixed-suffix
+@cindex @code{UR} fixed-suffix
+@cindex @code{ULR} fixed-suffix
+@cindex @code{ULLR} fixed-suffix
+@cindex @code{HK} fixed-suffix
+@cindex @code{K} fixed-suffix
+@cindex @code{LK} fixed-suffix
+@cindex @code{LLK} fixed-suffix
+@cindex @code{UHK} fixed-suffix
+@cindex @code{UK} fixed-suffix
+@cindex @code{ULK} fixed-suffix
+@cindex @code{ULLK} fixed-suffix
-Using the built-in functions described below, you can record
-the arguments a function received, and call another function
-with the same arguments, without knowing the number or types
-of the arguments.
+As an extension, GNU C supports fixed-point types as
+defined in the N1169 draft of ISO/IEC DTR 18037. Support for fixed-point
+types in GCC will evolve as the draft technical report changes.
+Calling conventions for any target might also change. Not all targets
+support fixed-point types.
-You can also record the return value of that function call,
-and later return that value, without knowing what data type
-the function tried to return (as long as your caller expects
-that data type).
+The fixed-point types are
+@code{short _Fract},
+@code{_Fract},
+@code{long _Fract},
+@code{long long _Fract},
+@code{unsigned short _Fract},
+@code{unsigned _Fract},
+@code{unsigned long _Fract},
+@code{unsigned long long _Fract},
+@code{_Sat short _Fract},
+@code{_Sat _Fract},
+@code{_Sat long _Fract},
+@code{_Sat long long _Fract},
+@code{_Sat unsigned short _Fract},
+@code{_Sat unsigned _Fract},
+@code{_Sat unsigned long _Fract},
+@code{_Sat unsigned long long _Fract},
+@code{short _Accum},
+@code{_Accum},
+@code{long _Accum},
+@code{long long _Accum},
+@code{unsigned short _Accum},
+@code{unsigned _Accum},
+@code{unsigned long _Accum},
+@code{unsigned long long _Accum},
+@code{_Sat short _Accum},
+@code{_Sat _Accum},
+@code{_Sat long _Accum},
+@code{_Sat long long _Accum},
+@code{_Sat unsigned short _Accum},
+@code{_Sat unsigned _Accum},
+@code{_Sat unsigned long _Accum},
+@code{_Sat unsigned long long _Accum}.
-However, these built-in functions may interact badly with some
-sophisticated features or other extensions of the language. It
-is, therefore, not recommended to use them outside very simple
-functions acting as mere forwarders for their arguments.
+Fixed-point data values contain fractional and optional integral parts.
+The format of fixed-point data varies and depends on the target machine.
-@defbuiltin{{void *} __builtin_apply_args ()}
-This built-in function returns a pointer to data
-describing how to perform a call with the same arguments as are passed
-to the current function.
+Support for fixed-point types includes:
+@itemize @bullet
+@item
+prefix and postfix increment and decrement operators (@code{++}, @code{--})
+@item
+unary arithmetic operators (@code{+}, @code{-}, @code{!})
+@item
+binary arithmetic operators (@code{+}, @code{-}, @code{*}, @code{/})
+@item
+binary shift operators (@code{<<}, @code{>>})
+@item
+relational operators (@code{<}, @code{<=}, @code{>=}, @code{>})
+@item
+equality operators (@code{==}, @code{!=})
+@item
+assignment operators (@code{+=}, @code{-=}, @code{*=}, @code{/=},
+@code{<<=}, @code{>>=})
+@item
+conversions to and from integer, floating-point, or fixed-point types
+@end itemize
-The function saves the arg pointer register, structure value address,
-and all registers that might be used to pass arguments to a function
-into a block of memory allocated on the stack. Then it returns the
-address of that block.
-@enddefbuiltin
+Use a suffix in a fixed-point literal constant:
+@itemize
+@item @samp{hr} or @samp{HR} for @code{short _Fract} and
+@code{_Sat short _Fract}
+@item @samp{r} or @samp{R} for @code{_Fract} and @code{_Sat _Fract}
+@item @samp{lr} or @samp{LR} for @code{long _Fract} and
+@code{_Sat long _Fract}
+@item @samp{llr} or @samp{LLR} for @code{long long _Fract} and
+@code{_Sat long long _Fract}
+@item @samp{uhr} or @samp{UHR} for @code{unsigned short _Fract} and
+@code{_Sat unsigned short _Fract}
+@item @samp{ur} or @samp{UR} for @code{unsigned _Fract} and
+@code{_Sat unsigned _Fract}
+@item @samp{ulr} or @samp{ULR} for @code{unsigned long _Fract} and
+@code{_Sat unsigned long _Fract}
+@item @samp{ullr} or @samp{ULLR} for @code{unsigned long long _Fract}
+and @code{_Sat unsigned long long _Fract}
+@item @samp{hk} or @samp{HK} for @code{short _Accum} and
+@code{_Sat short _Accum}
+@item @samp{k} or @samp{K} for @code{_Accum} and @code{_Sat _Accum}
+@item @samp{lk} or @samp{LK} for @code{long _Accum} and
+@code{_Sat long _Accum}
+@item @samp{llk} or @samp{LLK} for @code{long long _Accum} and
+@code{_Sat long long _Accum}
+@item @samp{uhk} or @samp{UHK} for @code{unsigned short _Accum} and
+@code{_Sat unsigned short _Accum}
+@item @samp{uk} or @samp{UK} for @code{unsigned _Accum} and
+@code{_Sat unsigned _Accum}
+@item @samp{ulk} or @samp{ULK} for @code{unsigned long _Accum} and
+@code{_Sat unsigned long _Accum}
+@item @samp{ullk} or @samp{ULLK} for @code{unsigned long long _Accum}
+and @code{_Sat unsigned long long _Accum}
+@end itemize
-@defbuiltin{{void *} __builtin_apply (void (*@var{function})(), void *@var{arguments}, size_t @var{size})}
-This built-in function invokes @var{function}
-with a copy of the parameters described by @var{arguments}
-and @var{size}.
+GCC support of fixed-point types as specified by the draft technical report
+is incomplete:
-The value of @var{arguments} should be the value returned by
-@code{__builtin_apply_args}. The argument @var{size} specifies the size
-of the stack argument data, in bytes.
+@itemize @bullet
+@item
+Pragmas to control overflow and rounding behaviors are not implemented.
+@end itemize
-This function returns a pointer to data describing
-how to return whatever value is returned by @var{function}. The data
-is saved in a block of memory allocated on the stack.
+Fixed-point types are supported by the DWARF debug information format.
-It is not always simple to compute the proper value for @var{size}. The
-value is used by @code{__builtin_apply} to compute the amount of data
-that should be pushed on the stack and copied from the incoming argument
-area.
-@enddefbuiltin
+@node Aggregate Types
+@section Array, Union, and Struct Extensions
-@defbuiltin{{void} __builtin_return (void *@var{result})}
-This built-in function returns the value described by @var{result} from
-the containing function. You should specify, for @var{result}, a value
-returned by @code{__builtin_apply}.
-@enddefbuiltin
+GCC supports several extensions relating to array, union, and struct types,
+including extensions for aggregate initializers for objects of these types.
+
+@menu
+* Variable Length:: Arrays whose length is computed at run time.
+* Zero Length:: Zero-length arrays.
+* Empty Structures:: Structures with no members.
+* Flexible Array Members in Unions:: Unions with Flexible Array Members.
+* Flexible Array Members alone in Structures:: Structures with only Flexible Array Members.
+* Unnamed Fields:: Unnamed struct/union fields within structs/unions.
+* Cast to Union:: Casting to union type from any member of the union.
+* Subscripting:: Any array can be subscripted, even if not an lvalue.
+* Initializers:: Non-constant initializers.
+* Compound Literals:: Compound literals give structures, unions
+ or arrays as values.
+* Designated Inits:: Labeling elements of initializers.
+@end menu
+
+@node Variable Length
+@subsection Arrays of Variable Length
+@cindex variable-length arrays
+@cindex arrays of variable length
+@cindex VLAs
+
+Variable-length automatic arrays are allowed in ISO C99, and as an
+extension GCC accepts them in C90 mode and in C++. These arrays are
+declared like any other automatic arrays, but with a length that is not
+a constant expression. The storage is allocated at the point of
+declaration and deallocated when the block scope containing the declaration
+exits. For
+example:
-@defbuiltin{{} __builtin_va_arg_pack ()}
-This built-in function represents all anonymous arguments of an inline
-function. It can be used only in inline functions that are always
-inlined, never compiled as a separate function, such as those using
-@code{__attribute__ ((__always_inline__))} or
-@code{__attribute__ ((__gnu_inline__))} extern inline functions.
-It must be only passed as last argument to some other function
-with variable arguments. This is useful for writing small wrapper
-inlines for variable argument functions, when using preprocessor
-macros is undesirable. For example:
@smallexample
-extern int myprintf (FILE *f, const char *format, ...);
-extern inline __attribute__ ((__gnu_inline__)) int
-myprintf (FILE *f, const char *format, ...)
+FILE *
+concat_fopen (char *s1, char *s2, char *mode)
@{
- int r = fprintf (f, "myprintf: ");
- if (r < 0)
- return r;
- int s = fprintf (f, format, __builtin_va_arg_pack ());
- if (s < 0)
- return s;
- return r + s;
+ char str[strlen (s1) + strlen (s2) + 1];
+ strcpy (str, s1);
+ strcat (str, s2);
+ return fopen (str, mode);
@}
@end smallexample
-@enddefbuiltin
-
-@defbuiltin{int __builtin_va_arg_pack_len ()}
-This built-in function returns the number of anonymous arguments of
-an inline function. It can be used only in inline functions that
-are always inlined, never compiled as a separate function, such
-as those using @code{__attribute__ ((__always_inline__))} or
-@code{__attribute__ ((__gnu_inline__))} extern inline functions.
-For example following does link- or run-time checking of open
-arguments for optimized code:
-@smallexample
-#ifdef __OPTIMIZE__
-extern inline __attribute__((__gnu_inline__)) int
-myopen (const char *path, int oflag, ...)
-@{
- if (__builtin_va_arg_pack_len () > 1)
- warn_open_too_many_arguments ();
- if (__builtin_constant_p (oflag))
- @{
- if ((oflag & O_CREAT) != 0 && __builtin_va_arg_pack_len () < 1)
- @{
- warn_open_missing_mode ();
- return __open_2 (path, oflag);
- @}
- return open (path, oflag, __builtin_va_arg_pack ());
- @}
+@cindex scope of a variable length array
+@cindex variable-length array scope
+@cindex deallocating variable length arrays
+Jumping or breaking out of the scope of the array name deallocates the
+storage. Jumping into the scope is not allowed; you get an error
+message for it.
- if (__builtin_va_arg_pack_len () < 1)
- return __open_2 (path, oflag);
+@cindex variable-length array in a structure
+As an extension, GCC accepts variable-length arrays as a member of
+a structure or a union. For example:
- return open (path, oflag, __builtin_va_arg_pack ());
+@smallexample
+void
+foo (int n)
+@{
+ struct S @{ int x[n]; @};
@}
-#endif
@end smallexample
-@enddefbuiltin
-@node Typeof
-@section Referring to a Type with @code{typeof}
-@findex typeof
-@findex sizeof
-@cindex macros, types of arguments
+@cindex @code{alloca} vs variable-length arrays
+You can use the function @code{alloca} to get an effect much like
+variable-length arrays. The function @code{alloca} is available in
+many other C implementations (but not in all). On the other hand,
+variable-length arrays are more elegant.
-Another way to refer to the type of an expression is with @code{typeof}.
-The syntax of using of this keyword looks like @code{sizeof}, but the
-construct acts semantically like a type name defined with @code{typedef}.
+There are other differences between these two methods. Space allocated
+with @code{alloca} exists until the containing @emph{function} returns.
+The space for a variable-length array is deallocated as soon as the array
+name's scope ends, unless you also use @code{alloca} in this scope.
-There are two ways of writing the argument to @code{typeof}: with an
-expression or with a type. Here is an example with an expression:
+You can also use variable-length arrays as arguments to functions:
@smallexample
-typeof (x[0](1))
+struct entry
+tester (int len, char data[len][len])
+@{
+ /* @r{@dots{}} */
+@}
@end smallexample
-@noindent
-This assumes that @code{x} is an array of pointers to functions;
-the type described is that of the values of the functions.
+The length of an array is computed once when the storage is allocated
+and is remembered for the scope of the array in case you access it with
+@code{sizeof}.
-Here is an example with a typename as the argument:
+If you want to pass the array first and the length afterward, you can
+use a forward declaration in the parameter list---another GNU extension.
@smallexample
-typeof (int *)
+struct entry
+tester (int len; char data[len][len], int len)
+@{
+ /* @r{@dots{}} */
+@}
@end smallexample
-@noindent
-Here the type described is that of pointers to @code{int}.
-
-If you are writing a header file that must work when included in ISO C
-programs, write @code{__typeof__} instead of @code{typeof}.
-@xref{Alternate Keywords}.
+@cindex parameter forward declaration
+The @samp{int len} before the semicolon is a @dfn{parameter forward
+declaration}, and it serves the purpose of making the name @code{len}
+known when the declaration of @code{data} is parsed.
-A @code{typeof} construct can be used anywhere a typedef name can be
-used. For example, you can use it in a declaration, in a cast, or inside
-of @code{sizeof} or @code{typeof}.
+You can write any number of such parameter forward declarations in the
+parameter list. They can be separated by commas or semicolons, but the
+last one must end with a semicolon, which is followed by the ``real''
+parameter declarations. Each forward declaration must match a ``real''
+declaration in parameter name and data type. ISO C99 does not support
+parameter forward declarations.
-The operand of @code{typeof} is evaluated for its side effects if and
-only if it is an expression of variably modified type or the name of
-such a type.
+@node Zero Length
+@subsection Arrays of Length Zero
+@cindex arrays of length zero
+@cindex zero-length arrays
+@cindex length-zero arrays
+@cindex flexible array members
-@code{typeof} is often useful in conjunction with
-statement expressions (@pxref{Statement Exprs}).
-Here is how the two together can
-be used to define a safe ``maximum'' macro which operates on any
-arithmetic type and evaluates each of its arguments exactly once:
+Declaring zero-length arrays is allowed in GNU C as an extension.
+A zero-length array can be useful as the last element of a structure
+that is really a header for a variable-length object:
@smallexample
-#define max(a,b) \
- (@{ typeof (a) _a = (a); \
- typeof (b) _b = (b); \
- _a > _b ? _a : _b; @})
-@end smallexample
+struct line @{
+ int length;
+ char contents[0];
+@};
-@cindex underscores in variables in macros
-@cindex @samp{_} in variables in macros
-@cindex local variables in macros
-@cindex variables, local, in macros
-@cindex macros, local variables in
+struct line *thisline = (struct line *)
+ malloc (sizeof (struct line) + this_length);
+thisline->length = this_length;
+@end smallexample
-The reason for using names that start with underscores for the local
-variables is to avoid conflicts with variable names that occur within the
-expressions that are substituted for @code{a} and @code{b}. Eventually we
-hope to design a new form of declaration syntax that allows you to declare
-variables whose scopes start only after their initializers; this will be a
-more reliable way to prevent such conflicts.
+In this example, @code{thisline->contents} is an array of @code{char} that
+can hold up to @code{thisline->length} bytes.
-@noindent
-Some more examples of the use of @code{typeof}:
+Although the size of a zero-length array is zero, an array member of
+this kind may increase the size of the enclosing type as a result of tail
+padding. The offset of a zero-length array member from the beginning
+of the enclosing structure is the same as the offset of an array with
+one or more elements of the same type. The alignment of a zero-length
+array is the same as the alignment of its elements.
+
+Declaring zero-length arrays in other contexts, including as interior
+members of structure objects or as non-member objects, is discouraged.
+Accessing elements of zero-length arrays declared in such contexts is
+undefined and may be diagnosed.
+
+In the absence of the zero-length array extension, in ISO C90
+the @code{contents} array in the example above would typically be declared
+to have a single element. Unlike a zero-length array which only contributes
+to the size of the enclosing structure for the purposes of alignment,
+a one-element array always occupies at least as much space as a single
+object of the type. Although using one-element arrays this way is
+discouraged, GCC handles accesses to trailing one-element array members
+analogously to zero-length arrays.
+
+The preferred mechanism to declare variable-length types like
+@code{struct line} above is the ISO C99 @dfn{flexible array member},
+with slightly different syntax and semantics:
@itemize @bullet
@item
-This declares @code{y} with the type of what @code{x} points to.
+Flexible array members are written as @code{contents[]} without
+the @code{0}.
-@smallexample
-typeof (*x) y;
-@end smallexample
+@item
+Flexible array members have incomplete type, and so the @code{sizeof}
+operator may not be applied. As a quirk of the original implementation
+of zero-length arrays, @code{sizeof} evaluates to zero.
@item
-This declares @code{y} as an array of such values.
+Flexible array members may only appear as the last member of a
+@code{struct} that is otherwise non-empty.
+
+@item
+A structure containing a flexible array member, or a union containing
+such a structure (possibly recursively), may not be a member of a
+structure or an element of an array. (However, these uses are
+permitted by GCC as extensions, see details below.)
+@end itemize
+
+The GCC extension accepts a structure containing an ISO C99 @dfn{flexible array
+member}, or a union containing such a structure (possibly recursively)
+to be a member of a structure.
+
+There are two situations:
+
+@itemize @bullet
+@item
+A structure containing a C99 flexible array member, or a union containing
+such a structure, is the last field of another structure, for example:
@smallexample
-typeof (*x) y[4];
+struct flex @{ int length; char data[]; @};
+union union_flex @{ int others; struct flex f; @};
+
+struct out_flex_struct @{ int m; struct flex flex_data; @};
+struct out_flex_union @{ int n; union union_flex flex_data; @};
@end smallexample
+In the above, both @code{out_flex_struct.flex_data.data[]} and
+@code{out_flex_union.flex_data.f.data[]} are considered as flexible arrays too.
+
@item
-This declares @code{y} as an array of pointers to characters:
+A structure containing a C99 flexible array member, or a union containing
+such a structure, is not the last field of another structure, for example:
@smallexample
-typeof (typeof (char *)[4]) y;
+struct flex @{ int length; char data[]; @};
+
+struct mid_flex @{ int m; struct flex flex_data; int n; @};
@end smallexample
-@noindent
-It is equivalent to the following traditional C declaration:
+In the above, accessing a member of the array @code{mid_flex.flex_data.data[]}
+might have undefined behavior. Compilers do not handle such a case
+consistently. Any code relying on this case should be modified to ensure
+that flexible array members only end up at the ends of structures.
+
+Please use the warning option @option{-Wflex-array-member-not-at-end} to
+identify all such cases in the source code and modify them. This extension
+is now deprecated.
+@end itemize
+
+Non-empty initialization of zero-length
+arrays is treated like any case where there are more initializer
+elements than the array holds, in that a suitable warning about ``excess
+elements in array'' is given, and the excess elements (all of them, in
+this case) are ignored.
+
+GCC allows static initialization of flexible array members.
+This is equivalent to defining a new structure containing the original
+structure followed by an array of sufficient size to contain the data.
+E.g.@: in the following, @code{f1} is constructed as if it were declared
+like @code{f2}.
@smallexample
-char *y[4];
+struct f1 @{
+ int x; int y[];
+@} f1 = @{ 1, @{ 2, 3, 4 @} @};
+
+struct f2 @{
+ struct f1 f1; int data[3];
+@} f2 = @{ @{ 1 @}, @{ 2, 3, 4 @} @};
@end smallexample
-To see the meaning of the declaration using @code{typeof}, and why it
-might be a useful way to write, rewrite it with these macros:
+@noindent
+The convenience of this extension is that @code{f1} has the desired
+type, eliminating the need to consistently refer to @code{f2.f1}.
+
+This has symmetry with normal static arrays, in that an array of
+unknown size is also written with @code{[]}.
+
+Of course, this extension only makes sense if the extra data comes at
+the end of a top-level object, as otherwise we would be overwriting
+data at subsequent offsets. To avoid undue complication and confusion
+with initialization of deeply nested arrays, we simply disallow any
+non-empty initialization except when the structure is the top-level
+object. For example:
@smallexample
-#define pointer(T) typeof(T *)
-#define array(T, N) typeof(T [N])
+struct foo @{ int x; int y[]; @};
+struct bar @{ struct foo z; @};
+
+struct foo a = @{ 1, @{ 2, 3, 4 @} @}; // @r{Valid.}
+struct bar b = @{ @{ 1, @{ 2, 3, 4 @} @} @}; // @r{Invalid.}
+struct bar c = @{ @{ 1, @{ @} @} @}; // @r{Valid.}
+struct foo d[1] = @{ @{ 1, @{ 2, 3, 4 @} @} @}; // @r{Invalid.}
@end smallexample
-@noindent
-Now the declaration can be rewritten this way:
+@node Empty Structures
+@subsection Structures with No Members
+@cindex empty structures
+@cindex zero-size structures
+
+GCC permits a C structure to have no members:
@smallexample
-array (pointer (char), 4) y;
+struct empty @{
+@};
@end smallexample
-@noindent
-Thus, @code{array (pointer (char), 4)} is the type of arrays of 4
-pointers to @code{char}.
-@end itemize
+The structure has size zero. In C++, empty structures are part
+of the language. G++ treats empty structures as if they had a single
+member of type @code{char}.
-The ISO C23 operator @code{typeof_unqual} is available in ISO C23 mode
-and its result is the non-atomic unqualified version of what @code{typeof}
-operator returns. Alternate spelling @code{__typeof_unqual__} is
-available in all C modes and provides non-atomic unqualified version of
-what @code{__typeof__} operator returns.
-@xref{Alternate Keywords}.
+@node Flexible Array Members in Unions
+@subsection Unions with Flexible Array Members
+@cindex unions with flexible array members
+@cindex unions with FAMs
-@cindex @code{__auto_type} in GNU C
-In GNU C, but not GNU C++, you may also declare the type of a variable
-as @code{__auto_type}. In that case, the declaration must declare
-only one variable, whose declarator must just be an identifier, the
-declaration must be initialized, and the type of the variable is
-determined by the initializer; the name of the variable is not in
-scope until after the initializer. (In C++, you should use C++11
-@code{auto} for this purpose.) Using @code{__auto_type}, the
-``maximum'' macro above could be written as:
+GCC permits a C99 flexible array member (FAM) to be in a union:
@smallexample
-#define max(a,b) \
- (@{ __auto_type _a = (a); \
- __auto_type _b = (b); \
- _a > _b ? _a : _b; @})
+union with_fam @{
+ int a;
+ int b[];
+@};
@end smallexample
-Using @code{__auto_type} instead of @code{typeof} has two advantages:
+If every member of a union is a flexible array member, the size of
+such a union is zero.
-@itemize @bullet
-@item Each argument to the macro appears only once in the expansion of
-the macro. This prevents the size of the macro expansion growing
-exponentially when calls to such macros are nested inside arguments of
-such macros.
+@node Flexible Array Members alone in Structures
+@subsection Structures with only Flexible Array Members
+@cindex structures with only flexible array members
+@cindex structures with only FAMs
-@item If the argument to the macro has variably modified type, it is
-evaluated only once when using @code{__auto_type}, but twice if
-@code{typeof} is used.
-@end itemize
+GCC permits a C99 flexible array member (FAM) to be alone in a structure:
-@node Conditionals
-@section Conditionals with Omitted Operands
-@cindex conditional expressions, extensions
-@cindex omitted middle-operands
-@cindex middle-operands, omitted
-@cindex extensions, @code{?:}
-@cindex @code{?:} extensions
+@smallexample
+struct only_fam @{
+ int b[];
+@};
+@end smallexample
-The middle operand in a conditional expression may be omitted. Then
-if the first operand is nonzero, its value is the value of the conditional
-expression.
+The size of such a structure is zero.
-Therefore, the expression
+@node Unnamed Fields
+@subsection Unnamed Structure and Union Fields
+@cindex @code{struct}
+@cindex @code{union}
+
+As permitted by ISO C11 and for compatibility with other compilers,
+GCC allows you to define
+a structure or union that contains, as fields, structures and unions
+without names. For example:
@smallexample
-x ? : y
+struct @{
+ int a;
+ union @{
+ int b;
+ float c;
+ @};
+ int d;
+@} foo;
@end smallexample
@noindent
-has the value of @code{x} if that is nonzero; otherwise, the value of
-@code{y}.
+In this example, you are able to access members of the unnamed
+union with code like @samp{foo.b}. Note that only unnamed structs and
+unions are allowed, you may not have, for example, an unnamed
+@code{int}.
-This example is perfectly equivalent to
+You must never create such structures that cause ambiguous field definitions.
+For example, in this structure:
@smallexample
-x ? x : y
+struct @{
+ int a;
+ struct @{
+ int a;
+ @};
+@} foo;
@end smallexample
-@cindex side effect in @code{?:}
-@cindex @code{?:} side effect
@noindent
-In this simple case, the ability to omit the middle operand is not
-especially useful. When it becomes useful is when the first operand does,
-or may (if it is a macro argument), contain a side effect. Then repeating
-the operand in the middle would perform the side effect twice. Omitting
-the middle operand uses the value already computed without the undesirable
-effects of recomputing it.
+it is ambiguous which @code{a} is being referred to with @samp{foo.a}.
+The compiler gives errors for such constructs.
-@node Additional Numeric Types
-@section Additional Numeric Types
+@opindex fms-extensions
+Unless @option{-fms-extensions} is used, the unnamed field must be a
+structure or union definition without a tag (for example, @samp{struct
+@{ int a; @};}). If @option{-fms-extensions} is used, the field may
+also be a definition with a tag such as @samp{struct foo @{ int a;
+@};}, a reference to a previously defined structure or union such as
+@samp{struct foo;}, or a reference to a @code{typedef} name for a
+previously defined structure or union type.
-GCC supports additional numeric types, including larger integer types,
-integer and floating-point complex types,
-additional floating-point sizes and formats, decimal floating types,
-and fixed-point types.
+@opindex fplan9-extensions
+The option @option{-fplan9-extensions} enables
+@option{-fms-extensions} as well as two other extensions. First, a
+pointer to a structure is automatically converted to a pointer to an
+anonymous field for assignments and function calls. For example:
-@menu
-* __int128:: 128-bit integers---@code{__int128}.
-* Long Long:: Double-word integers---@code{long long int}.
-* Complex:: Data types for complex numbers.
-* Floating Types:: Additional Floating Types.
-* Half-Precision:: Half-Precision Floating Point.
-* Decimal Float:: Decimal Floating Types.
-* Fixed-Point:: Fixed-Point Types.
-@end menu
+@smallexample
+struct s1 @{ int a; @};
+struct s2 @{ struct s1; @};
+extern void f1 (struct s1 *);
+void f2 (struct s2 *p) @{ f1 (p); @}
+@end smallexample
-@node __int128
-@subsection 128-bit Integers
-@cindex @code{__int128} data types
+@noindent
+In the call to @code{f1} inside @code{f2}, the pointer @code{p} is
+converted into a pointer to the anonymous field.
-As an extension the integer scalar type @code{__int128} is supported for
-targets which have an integer mode wide enough to hold 128 bits.
-Simply write @code{__int128} for a signed 128-bit integer, or
-@code{unsigned __int128} for an unsigned 128-bit integer. There is no
-support in GCC for expressing an integer constant of type @code{__int128}
-for targets with @code{long long} integer less than 128 bits wide.
+Second, when the type of an anonymous field is a @code{typedef} for a
+@code{struct} or @code{union}, code may refer to the field using the
+name of the @code{typedef}.
-@node Long Long
-@subsection Double-Word Integers
-@cindex @code{long long} data types
-@cindex double-word arithmetic
-@cindex multiprecision arithmetic
-@cindex @code{LL} integer suffix
-@cindex @code{ULL} integer suffix
+@smallexample
+typedef struct @{ int a; @} s1;
+struct s2 @{ s1; @};
+s1 f1 (struct s2 *p) @{ return p->s1; @}
+@end smallexample
-ISO C99 and ISO C++11 support data types for integers that are at least
-64 bits wide, and as an extension GCC supports them in C90 and C++98 modes.
-Simply write @code{long long int} for a signed integer, or
-@code{unsigned long long int} for an unsigned integer. To make an
-integer constant of type @code{long long int}, add the suffix @samp{LL}
-to the integer. To make an integer constant of type @code{unsigned long
-long int}, add the suffix @samp{ULL} to the integer.
+These usages are only permitted when they are not ambiguous.
-You can use these types in arithmetic like any other integer types.
-Addition, subtraction, and bitwise boolean operations on these types
-are open-coded on all types of machines. Multiplication is open-coded
-if the machine supports a fullword-to-doubleword widening multiply
-instruction. Division and shifts are open-coded only on machines that
-provide special support. The operations that are not open-coded use
-special library routines that come with GCC@.
+@node Cast to Union
+@subsection Cast to a Union Type
+@cindex cast to a union
+@cindex union, casting to a
-There may be pitfalls when you use @code{long long} types for function
-arguments without function prototypes. If a function
-expects type @code{int} for its argument, and you pass a value of type
-@code{long long int}, confusion results because the caller and the
-subroutine disagree about the number of bytes for the argument.
-Likewise, if the function expects @code{long long int} and you pass
-@code{int}. The best way to avoid such problems is to use prototypes.
+A cast to a union type is a C extension not available in C++. It looks
+just like ordinary casts with the constraint that the type specified is
+a union type. You can specify the type either with the @code{union}
+keyword or with a @code{typedef} name that refers to a union. The result
+of a cast to a union is a temporary rvalue of the union type with a member
+whose type matches that of the operand initialized to the value of
+the operand. The effect of a cast to a union is similar to a compound
+literal except that it yields an rvalue like standard casts do.
+@xref{Compound Literals}.
-@node Complex
-@subsection Complex Numbers
-@cindex complex numbers
-@cindex @code{_Complex} keyword
-@cindex @code{__complex__} keyword
+Expressions that may be cast to the union type are those whose type matches
+at least one of the members of the union. Thus, given the following union
+and variables:
-ISO C99 supports complex floating data types, and as an extension GCC
-supports them in C90 mode and in C++. GCC also supports complex integer data
-types which are not part of ISO C99. You can declare complex types
-using the keyword @code{_Complex}. As an extension, the older GNU
-keyword @code{__complex__} is also supported.
+@smallexample
+union foo @{ int i; double d; @};
+int x;
+double y;
+union foo z;
+@end smallexample
-For example, @samp{_Complex double x;} declares @code{x} as a
-variable whose real part and imaginary part are both of type
-@code{double}. @samp{_Complex short int y;} declares @code{y} to
-have real and imaginary parts of type @code{short int}; this is not
-likely to be useful, but it shows that the set of complex types is
-complete.
+@noindent
+both @code{x} and @code{y} can be cast to type @code{union foo} and
+the following assignments
+@smallexample
+ z = (union foo) x;
+ z = (union foo) y;
+@end smallexample
+are shorthand equivalents of these
+@smallexample
+ z = (union foo) @{ .i = x @};
+ z = (union foo) @{ .d = y @};
+@end smallexample
-To write a constant with a complex data type, use the suffix @samp{i},
-@samp{I}, @samp{j} or @samp{J} (any one; they are equivalent). For
-example, @code{2.5fi} has type @code{_Complex float} and @code{3i} has type
-@code{_Complex int}. Such a constant always has a pure imaginary
-value, but you can form any complex value you like by adding one to a
-real constant. This is part of ISO C2Y and for older C revisions
-a GNU extension. If you have an ISO C99 conforming C library
-(such as the GNU C Library), and want to construct complex
-constants of floating type when using standard versions before ISO C2Y,
-you should include @code{<complex.h>} and use the macros @code{I} or
-@code{_Complex_I} instead.
+However, @code{(union foo) FLT_MAX;} is not a valid cast because the union
+has no member of type @code{float}.
-For C++ if @code{-fext-numeric-literals} option is enabled, it is also
-a GNU extension, otherwise it is handled like any other C++ user-defined
-literal. The ISO C++14 library also defines the @samp{i} suffix, so C++14
-code that includes the @samp{<complex>} header cannot use @samp{i} for the
-GNU extension. The @samp{I}, @samp{j} or @samp{J} suffixes still have
-the GNU meaning.
+Using the cast as the right-hand side of an assignment to a variable of
+union type is equivalent to storing in a member of the union with
+the same type
-GCC handles both implicit and explicit casts between the
-@code{_Complex} types with different scalar base types by casting both
-the real and imaginary parts to the base type of the result.
-GCC also handles implicit and explicit casts from a scalar type to a
-@code{_Complex} type, by giving the imaginary part a zero value.
+@smallexample
+union foo u;
+/* @r{@dots{}} */
+u = (union foo) x @equiv{} u.i = x
+u = (union foo) y @equiv{} u.d = y
+@end smallexample
-The C front end can handle implicit and explicit casts from a
-@code{_Complex} type to a scalar type, which uses the value of the
-real part and ignores the imaginary part. In C++ code, this cast is
-considered ill-formed and G++ diagnoses it as an error.
+You can also use the union cast as a function argument:
-@cindex @code{__real__} keyword
-@cindex @code{__imag__} keyword
+@smallexample
+void hack (union foo);
+/* @r{@dots{}} */
+hack ((union foo) x);
+@end smallexample
-GCC has a few extensions which can be used to extract the real
-and the imaginary part of the complex-valued expression. Note
-these expressions are lvalues if the @var{exp} is an lvalue.
-These expressions operands have the type of a complex type
-which might get promoted to a complex type from a scalar type.
-E.g. @code{__real__ (int)@var{x}} is the same as casting to
-@code{_Complex int} before @code{__real__} is done.
+@node Subscripting
+@subsection Non-Lvalue Arrays May Have Subscripts
+@cindex subscripting
+@cindex arrays, non-lvalue
-@multitable @columnfractions .4 .6
-@headitem Expression @tab Description
-@item @code{__real__ @var{exp}}
-@tab Extract the real part of @var{exp}.
-@item @code{__imag__ @var{exp}}
-@tab Extract the imaginary part of @var{exp}.
-@end multitable
+@cindex subscripting and function values
+In ISO C99, arrays that are not lvalues still decay to pointers, and
+may be subscripted, although they may not be modified or used after
+the next sequence point and the unary @samp{&} operator may not be
+applied to them. As an extension, GNU C allows such arrays to be
+subscripted in C90 mode, though otherwise they do not decay to
+pointers outside C99 mode. For example,
+this is valid in GNU C though not valid in C90:
-For values of floating-point type, you should use the ISO C99
-functions, declared in @code{<complex.h>} and also provided as
-built-in functions by GCC@.
+@smallexample
+@group
+struct foo @{int a[4];@};
-@multitable @columnfractions .4 .2 .2 .2
-@headitem Expression @tab float @tab double @tab long double
-@item @code{__real__ @var{exp}}
-@tab @code{crealf} @tab @code{creal} @tab @code{creall}
-@item @code{__imag__ @var{exp}}
-@tab @code{cimagf} @tab @code{cimag} @tab @code{cimagl}
-@end multitable
+struct foo f();
-@cindex complex conjugation
-The operator @samp{~} performs complex conjugation when used on a value
-with a complex type. This is a GNU extension; for values of
-floating type, you should use the ISO C99 functions @code{conjf},
-@code{conj} and @code{conjl}, declared in @code{<complex.h>} and also
-provided as built-in functions by GCC@. Note unlike the @code{__real__}
-and @code{__imag__} operators, this operator does not do an implicit cast
-to the complex type because the @samp{~} is already a normal operator.
+bar (int index)
+@{
+ return f().a[index];
+@}
+@end group
+@end smallexample
-GCC can allocate complex automatic variables in a noncontiguous
-fashion; it's even possible for the real part to be in a register while
-the imaginary part is on the stack (or vice versa). Only the DWARF
-debug info format can represent this, so use of DWARF is recommended.
-If you are using the stabs debug info format, GCC describes a noncontiguous
-complex variable as if it were two separate variables of noncomplex type.
-If the variable's actual name is @code{foo}, the two fictitious
-variables are named @code{foo$real} and @code{foo$imag}. You can
-examine and set these two fictitious variables with your debugger.
+@node Initializers
+@subsection Non-Constant Initializers
+@cindex initializers, non-constant
+@cindex non-constant initializers
-@defbuiltin{@var{type} __builtin_complex (@var{real}, @var{imag})}
-
-The built-in function @code{__builtin_complex} is provided for use in
-implementing the ISO C11 macros @code{CMPLXF}, @code{CMPLX} and
-@code{CMPLXL}. @var{real} and @var{imag} must have the same type, a
-real binary floating-point type, and the result has the corresponding
-complex type with real and imaginary parts @var{real} and @var{imag}.
-Unlike @samp{@var{real} + I * @var{imag}}, this works even when
-infinities, NaNs and negative zeros are involved.
+As in standard C++ and ISO C99, the elements of an aggregate initializer for an
+automatic variable are not required to be constant expressions in GNU C@.
+Here is an example of an initializer with run-time varying elements:
-@enddefbuiltin
+@smallexample
+foo (float f, float g)
+@{
+ float beat_freqs[2] = @{ f-g, f+g @};
+ /* @r{@dots{}} */
+@}
+@end smallexample
-@node Floating Types
-@subsection Additional Floating Types
-@cindex additional floating types
-@cindex @code{_Float@var{n}} data types
-@cindex @code{_Float@var{n}x} data types
-@cindex @code{__float80} data type
-@cindex @code{__float128} data type
-@cindex @code{__ibm128} data type
-@cindex @code{w} floating point suffix
-@cindex @code{q} floating point suffix
-@cindex @code{W} floating point suffix
-@cindex @code{Q} floating point suffix
+@node Compound Literals
+@subsection Compound Literals
+@cindex constructor expressions
+@cindex initializations in expressions
+@cindex structures, constructor expression
+@cindex expressions, constructor
+@cindex compound literals
+@c The GNU C name for what C99 calls compound literals was "constructor expressions".
-ISO/IEC TS 18661-3:2015 defines C support for additional floating
-types @code{_Float@var{n}} and @code{_Float@var{n}x}, and GCC supports
-these type names; the set of types supported depends on the target
-architecture.
-Constants with these types use suffixes @code{f@var{n}} or
-@code{F@var{n}} and @code{f@var{n}x} or @code{F@var{n}x}. These type
-names can be used together with @code{_Complex} to declare complex
-types.
+A compound literal looks like a cast of a brace-enclosed aggregate
+initializer list. Its value is an object of the type specified in
+the cast, containing the elements specified in the initializer.
+Unlike the result of a cast, a compound literal is an lvalue. ISO
+C99 and later support compound literals. As an extension, GCC
+supports compound literals also in C90 mode and in C++, although
+as explained below, the C++ semantics are somewhat different.
-As an extension, GNU C and GNU C++ support additional floating
-types, which are not supported by all targets.
-@itemize @bullet
-@item @code{__float128} is available on i386, x86_64, IA-64, LoongArch
-and hppa HP-UX, as well as on PowerPC GNU/Linux targets that enable
-the vector scalar (VSX) instruction set. @code{__float128} supports
-the 128-bit floating type. On i386, x86_64, PowerPC, LoongArch and IA-64,
-other than HP-UX, @code{__float128} is an alias for @code{_Float128}.
-On hppa and IA-64 HP-UX, @code{__float128} is an alias for @code{long
-double}.
+Usually, the specified type of a compound literal is a structure. Assume
+that @code{struct foo} and @code{structure} are declared as shown:
-@item @code{__float80} is available on the i386, x86_64, and IA-64
-targets, and supports the 80-bit (@code{XFmode}) floating type. It is
-an alias for the type name @code{_Float64x} on these targets.
+@smallexample
+struct foo @{int a; char b[2];@} structure;
+@end smallexample
-@item @code{__ibm128} is available on PowerPC targets, and provides
-access to the IBM extended double format which is the current format
-used for @code{long double}. When @code{long double} transitions to
-@code{__float128} on PowerPC in the future, @code{__ibm128} will remain
-for use in conversions between the two types.
-@end itemize
+@noindent
+Here is an example of constructing a @code{struct foo} with a compound literal:
-Support for these additional types includes the arithmetic operators:
-add, subtract, multiply, divide; unary arithmetic operators;
-relational operators; equality operators; and conversions to and from
-integer and other floating types. Use a suffix @samp{w} or @samp{W}
-in a literal constant of type @code{__float80} or type
-@code{__ibm128}. Use a suffix @samp{q} or @samp{Q} for @code{__float128}.
+@smallexample
+structure = ((struct foo) @{x + y, 'a', 0@});
+@end smallexample
-In order to use @code{_Float128}, @code{__float128}, and @code{__ibm128}
-on PowerPC Linux systems, you must use the @option{-mfloat128} option. It is
-expected in future versions of GCC that @code{_Float128} and @code{__float128}
-will be enabled automatically.
+@noindent
+This is equivalent to writing the following:
-The @code{_Float128} type is supported on all systems where
-@code{__float128} is supported or where @code{long double} has the
-IEEE binary128 format. The @code{_Float64x} type is supported on all
-systems where @code{__float128} is supported. The @code{_Float32}
-type is supported on all systems supporting IEEE binary32; the
-@code{_Float64} and @code{_Float32x} types are supported on all systems
-supporting IEEE binary64. The @code{_Float16} type is supported on AArch64
-systems by default, on ARM systems when the IEEE format for 16-bit
-floating-point types is selected with @option{-mfp16-format=ieee} and,
-for both C and C++, on x86 systems with SSE2 enabled. GCC does not currently
-support @code{_Float128x} on any systems.
+@smallexample
+@{
+ struct foo temp = @{x + y, 'a', 0@};
+ structure = temp;
+@}
+@end smallexample
-On the i386, x86_64, IA-64, and HP-UX targets, you can declare complex
-types using the corresponding internal complex type, @code{XCmode} for
-@code{__float80} type and @code{TCmode} for @code{__float128} type:
+You can also construct an array, though this is dangerous in C++, as
+explained below. If all the elements of the compound literal are
+(made up of) simple constant expressions suitable for use in
+initializers of objects of static storage duration, then the compound
+literal can be coerced to a pointer to its first element and used in
+such an initializer, as shown here:
@smallexample
-typedef _Complex float __attribute__((mode(TC))) _Complex128;
-typedef _Complex float __attribute__((mode(XC))) _Complex80;
+char **foo = (char *[]) @{ "x", "y", "z" @};
@end smallexample
-On the PowerPC Linux VSX targets, you can declare complex types using
-the corresponding internal complex type, @code{KCmode} for
-@code{__float128} type and @code{ICmode} for @code{__ibm128} type:
+Compound literals for scalar types and union types are also allowed. In
+the following example the variable @code{i} is initialized to the value
+@code{2}, the result of incrementing the unnamed object created by
+the compound literal.
@smallexample
-typedef _Complex float __attribute__((mode(KC))) _Complex_float128;
-typedef _Complex float __attribute__((mode(IC))) _Complex_ibm128;
+int i = ++(int) @{ 1 @};
@end smallexample
-@node Half-Precision
-@subsection Half-Precision Floating Point
-@cindex half-precision floating point
-@cindex @code{__fp16} data type
-@cindex @code{__Float16} data type
+As a GNU extension, GCC allows initialization of objects with static storage
+duration by compound literals (which is not possible in ISO C99 because
+the initializer is not a constant).
+It is handled as if the object were initialized only with the brace-enclosed
+list if the types of the compound literal and the object match.
+The elements of the compound literal must be constant.
+If the object being initialized has array type of unknown size, the size is
+determined by the size of the compound literal.
-On ARM and AArch64 targets, GCC supports half-precision (16-bit) floating
-point via the @code{__fp16} type defined in the ARM C Language Extensions.
-On ARM systems, you must enable this type explicitly with the
-@option{-mfp16-format} command-line option in order to use it.
-On x86 targets with SSE2 enabled, GCC supports half-precision (16-bit)
-floating point via the @code{_Float16} type. For C++, x86 provides a builtin
-type named @code{_Float16} which contains same data format as C.
+@smallexample
+static struct foo x = (struct foo) @{1, 'a', 'b'@};
+static int y[] = (int []) @{1, 2, 3@};
+static int z[] = (int [3]) @{1@};
+@end smallexample
-ARM targets support two incompatible representations for half-precision
-floating-point values. You must choose one of the representations and
-use it consistently in your program.
+@noindent
+The above lines are equivalent to the following:
+@smallexample
+static struct foo x = @{1, 'a', 'b'@};
+static int y[] = @{1, 2, 3@};
+static int z[] = @{1, 0, 0@};
+@end smallexample
-Specifying @option{-mfp16-format=ieee} selects the IEEE 754-2008 format.
-This format can represent normalized values in the range of @math{2^{-14}} to 65504.
-There are 11 bits of significand precision, approximately 3
-decimal digits.
+In C, a compound literal designates an unnamed object with static or
+automatic storage duration. In C++, a compound literal designates a
+temporary object that only lives until the end of its full-expression.
+As a result, well-defined C code that takes the address of a subobject
+of a compound literal can be undefined in C++, so G++ rejects
+the conversion of a temporary array to a pointer. For instance, if
+the array compound literal example above appeared inside a function,
+any subsequent use of @code{foo} in C++ would have undefined behavior
+because the lifetime of the array ends after the declaration of @code{foo}.
-Specifying @option{-mfp16-format=alternative} selects the ARM
-alternative format. This representation is similar to the IEEE
-format, but does not support infinities or NaNs. Instead, the range
-of exponents is extended, so that this format can represent normalized
-values in the range of @math{2^{-14}} to 131008.
+As an optimization, G++ sometimes gives array compound literals longer
+lifetimes: when the array either appears outside a function or has
+a @code{const}-qualified type. If @code{foo} and its initializer had
+elements of type @code{char *const} rather than @code{char *}, or if
+@code{foo} were a global variable, the array would have static storage
+duration. But it is probably safest just to avoid the use of array
+compound literals in C++ code.
-The GCC port for AArch64 only supports the IEEE 754-2008 format, and does
-not require use of the @option{-mfp16-format} command-line option.
+@node Designated Inits
+@subsection Designated Initializers
+@cindex initializers with labeled elements
+@cindex labeled elements in initializers
+@cindex case labels in initializers
+@cindex designated initializers
-The @code{__fp16} type may only be used as an argument to intrinsics defined
-in @code{<arm_fp16.h>}, or as a storage format. For purposes of
-arithmetic and other operations, @code{__fp16} values in C or C++
-expressions are automatically promoted to @code{float}.
+Standard C90 requires the elements of an initializer to appear in a fixed
+order, the same as the order of the elements in the array or structure
+being initialized.
-The ARM target provides hardware support for conversions between
-@code{__fp16} and @code{float} values
-as an extension to VFP and NEON (Advanced SIMD), and from ARMv8-A provides
-hardware support for conversions between @code{__fp16} and @code{double}
-values. GCC generates code using these hardware instructions if you
-compile with options to select an FPU that provides them;
-for example, @option{-mfpu=neon-fp16 -mfloat-abi=softfp},
-in addition to the @option{-mfp16-format} option to select
-a half-precision format.
+In ISO C99 you can give the elements in any order, specifying the array
+indices or structure field names they apply to, and GNU C allows this as
+an extension in C90 mode as well. This extension is not
+implemented in GNU C++.
-Language-level support for the @code{__fp16} data type is
-independent of whether GCC generates code using hardware floating-point
-instructions. In cases where hardware support is not specified, GCC
-implements conversions between @code{__fp16} and other types as library
-calls.
+To specify an array index, write
+@samp{[@var{index}] =} before the element value. For example,
-It is recommended that portable code use the @code{_Float16} type defined
-by ISO/IEC TS 18661-3:2015. @xref{Floating Types}.
+@smallexample
+int a[6] = @{ [4] = 29, [2] = 15 @};
+@end smallexample
-On x86 targets with SSE2 enabled, without @option{-mavx512fp16},
-all operations will be emulated by software emulation and the @code{float}
-instructions. The default behavior for @code{FLT_EVAL_METHOD} is to keep the
-intermediate result of the operation as 32-bit precision. This may lead to
-inconsistent behavior between software emulation and AVX512-FP16 instructions.
-Using @option{-fexcess-precision=16} will force round back after each operation.
+@noindent
+is equivalent to
-Using @option{-mavx512fp16} will generate AVX512-FP16 instructions instead of
-software emulation. The default behavior of @code{FLT_EVAL_METHOD} is to round
-after each operation. The same is true with @option{-fexcess-precision=standard}
-and @option{-mfpmath=sse}. If there is no @option{-mfpmath=sse},
-@option{-fexcess-precision=standard} alone does the same thing as before,
-It is useful for code that does not have @code{_Float16} and runs on the x87
-FPU.
+@smallexample
+int a[6] = @{ 0, 0, 15, 0, 29, 0 @};
+@end smallexample
-@node Decimal Float
-@subsection Decimal Floating Types
-@cindex decimal floating types
-@cindex @code{_Decimal32} data type
-@cindex @code{_Decimal64} data type
-@cindex @code{_Decimal128} data type
-@cindex @code{df} integer suffix
-@cindex @code{dd} integer suffix
-@cindex @code{dl} integer suffix
-@cindex @code{DF} integer suffix
-@cindex @code{DD} integer suffix
-@cindex @code{DL} integer suffix
+@noindent
+The index values must be constant expressions, even if the array being
+initialized is automatic.
-As an extension, GNU C supports decimal floating types as
-defined in the N1312 draft of ISO/IEC WDTR24732. Support for decimal
-floating types in GCC will evolve as the draft technical report changes.
-Calling conventions for any target might also change. Not all targets
-support decimal floating types.
+An alternative syntax for this that has been obsolete since GCC 2.5 but
+GCC still accepts is to write @samp{[@var{index}]} before the element
+value, with no @samp{=}.
-The decimal floating types are @code{_Decimal32}, @code{_Decimal64}, and
-@code{_Decimal128}. They use a radix of ten, unlike the floating types
-@code{float}, @code{double}, and @code{long double} whose radix is not
-specified by the C standard but is usually two.
+To initialize a range of elements to the same value, write
+@samp{[@var{first} ... @var{last}] = @var{value}}. This is a GNU
+extension. For example,
-Support for decimal floating types includes the arithmetic operators
-add, subtract, multiply, divide; unary arithmetic operators;
-relational operators; equality operators; and conversions to and from
-integer and other floating types. Use a suffix @samp{df} or
-@samp{DF} in a literal constant of type @code{_Decimal32}, @samp{dd}
-or @samp{DD} for @code{_Decimal64}, and @samp{dl} or @samp{DL} for
-@code{_Decimal128}.
+@smallexample
+int widths[] = @{ [0 ... 9] = 1, [10 ... 99] = 2, [100] = 3 @};
+@end smallexample
-GCC support of decimal float as specified by the draft technical report
-is incomplete:
+@noindent
+If the value in it has side effects, the side effects happen only once,
+not for each initialized field by the range initializer.
-@itemize @bullet
-@item
-When the value of a decimal floating type cannot be represented in the
-integer type to which it is being converted, the result is undefined
-rather than the result value specified by the draft technical report.
+@noindent
+Note that the length of the array is the highest value specified
+plus one.
-@item
-GCC does not provide the C library functionality associated with
-@file{math.h}, @file{fenv.h}, @file{stdio.h}, @file{stdlib.h}, and
-@file{wchar.h}, which must come from a separate C library implementation.
-Because of this the GNU C compiler does not define macro
-@code{__STDC_DEC_FP__} to indicate that the implementation conforms to
-the technical report.
-@end itemize
+In a structure initializer, specify the name of a field to initialize
+with @samp{.@var{fieldname} =} before the element value. For example,
+given the following structure,
-Types @code{_Decimal32}, @code{_Decimal64}, and @code{_Decimal128}
-are supported by the DWARF debug information format.
+@smallexample
+struct point @{ int x, y; @};
+@end smallexample
-@node Fixed-Point
-@subsection Fixed-Point Types
-@cindex fixed-point types
-@cindex @code{_Fract} data type
-@cindex @code{_Accum} data type
-@cindex @code{_Sat} data type
-@cindex @code{hr} fixed-suffix
-@cindex @code{r} fixed-suffix
-@cindex @code{lr} fixed-suffix
-@cindex @code{llr} fixed-suffix
-@cindex @code{uhr} fixed-suffix
-@cindex @code{ur} fixed-suffix
-@cindex @code{ulr} fixed-suffix
-@cindex @code{ullr} fixed-suffix
-@cindex @code{hk} fixed-suffix
-@cindex @code{k} fixed-suffix
-@cindex @code{lk} fixed-suffix
-@cindex @code{llk} fixed-suffix
-@cindex @code{uhk} fixed-suffix
-@cindex @code{uk} fixed-suffix
-@cindex @code{ulk} fixed-suffix
-@cindex @code{ullk} fixed-suffix
-@cindex @code{HR} fixed-suffix
-@cindex @code{R} fixed-suffix
-@cindex @code{LR} fixed-suffix
-@cindex @code{LLR} fixed-suffix
-@cindex @code{UHR} fixed-suffix
-@cindex @code{UR} fixed-suffix
-@cindex @code{ULR} fixed-suffix
-@cindex @code{ULLR} fixed-suffix
-@cindex @code{HK} fixed-suffix
-@cindex @code{K} fixed-suffix
-@cindex @code{LK} fixed-suffix
-@cindex @code{LLK} fixed-suffix
-@cindex @code{UHK} fixed-suffix
-@cindex @code{UK} fixed-suffix
-@cindex @code{ULK} fixed-suffix
-@cindex @code{ULLK} fixed-suffix
+@noindent
+the following initialization
-As an extension, GNU C supports fixed-point types as
-defined in the N1169 draft of ISO/IEC DTR 18037. Support for fixed-point
-types in GCC will evolve as the draft technical report changes.
-Calling conventions for any target might also change. Not all targets
-support fixed-point types.
+@smallexample
+struct point p = @{ .y = yvalue, .x = xvalue @};
+@end smallexample
-The fixed-point types are
-@code{short _Fract},
-@code{_Fract},
-@code{long _Fract},
-@code{long long _Fract},
-@code{unsigned short _Fract},
-@code{unsigned _Fract},
-@code{unsigned long _Fract},
-@code{unsigned long long _Fract},
-@code{_Sat short _Fract},
-@code{_Sat _Fract},
-@code{_Sat long _Fract},
-@code{_Sat long long _Fract},
-@code{_Sat unsigned short _Fract},
-@code{_Sat unsigned _Fract},
-@code{_Sat unsigned long _Fract},
-@code{_Sat unsigned long long _Fract},
-@code{short _Accum},
-@code{_Accum},
-@code{long _Accum},
-@code{long long _Accum},
-@code{unsigned short _Accum},
-@code{unsigned _Accum},
-@code{unsigned long _Accum},
-@code{unsigned long long _Accum},
-@code{_Sat short _Accum},
-@code{_Sat _Accum},
-@code{_Sat long _Accum},
-@code{_Sat long long _Accum},
-@code{_Sat unsigned short _Accum},
-@code{_Sat unsigned _Accum},
-@code{_Sat unsigned long _Accum},
-@code{_Sat unsigned long long _Accum}.
+@noindent
+is equivalent to
-Fixed-point data values contain fractional and optional integral parts.
-The format of fixed-point data varies and depends on the target machine.
+@smallexample
+struct point p = @{ xvalue, yvalue @};
+@end smallexample
-Support for fixed-point types includes:
-@itemize @bullet
-@item
-prefix and postfix increment and decrement operators (@code{++}, @code{--})
-@item
-unary arithmetic operators (@code{+}, @code{-}, @code{!})
-@item
-binary arithmetic operators (@code{+}, @code{-}, @code{*}, @code{/})
-@item
-binary shift operators (@code{<<}, @code{>>})
-@item
-relational operators (@code{<}, @code{<=}, @code{>=}, @code{>})
-@item
-equality operators (@code{==}, @code{!=})
-@item
-assignment operators (@code{+=}, @code{-=}, @code{*=}, @code{/=},
-@code{<<=}, @code{>>=})
-@item
-conversions to and from integer, floating-point, or fixed-point types
-@end itemize
+Another syntax that has the same meaning, obsolete since GCC 2.5, is
+@samp{@var{fieldname}:}, as shown here:
-Use a suffix in a fixed-point literal constant:
-@itemize
-@item @samp{hr} or @samp{HR} for @code{short _Fract} and
-@code{_Sat short _Fract}
-@item @samp{r} or @samp{R} for @code{_Fract} and @code{_Sat _Fract}
-@item @samp{lr} or @samp{LR} for @code{long _Fract} and
-@code{_Sat long _Fract}
-@item @samp{llr} or @samp{LLR} for @code{long long _Fract} and
-@code{_Sat long long _Fract}
-@item @samp{uhr} or @samp{UHR} for @code{unsigned short _Fract} and
-@code{_Sat unsigned short _Fract}
-@item @samp{ur} or @samp{UR} for @code{unsigned _Fract} and
-@code{_Sat unsigned _Fract}
-@item @samp{ulr} or @samp{ULR} for @code{unsigned long _Fract} and
-@code{_Sat unsigned long _Fract}
-@item @samp{ullr} or @samp{ULLR} for @code{unsigned long long _Fract}
-and @code{_Sat unsigned long long _Fract}
-@item @samp{hk} or @samp{HK} for @code{short _Accum} and
-@code{_Sat short _Accum}
-@item @samp{k} or @samp{K} for @code{_Accum} and @code{_Sat _Accum}
-@item @samp{lk} or @samp{LK} for @code{long _Accum} and
-@code{_Sat long _Accum}
-@item @samp{llk} or @samp{LLK} for @code{long long _Accum} and
-@code{_Sat long long _Accum}
-@item @samp{uhk} or @samp{UHK} for @code{unsigned short _Accum} and
-@code{_Sat unsigned short _Accum}
-@item @samp{uk} or @samp{UK} for @code{unsigned _Accum} and
-@code{_Sat unsigned _Accum}
-@item @samp{ulk} or @samp{ULK} for @code{unsigned long _Accum} and
-@code{_Sat unsigned long _Accum}
-@item @samp{ullk} or @samp{ULLK} for @code{unsigned long long _Accum}
-and @code{_Sat unsigned long long _Accum}
-@end itemize
+@smallexample
+struct point p = @{ y: yvalue, x: xvalue @};
+@end smallexample
-GCC support of fixed-point types as specified by the draft technical report
-is incomplete:
+Omitted fields are implicitly initialized the same as for objects
+that have static storage duration.
-@itemize @bullet
-@item
-Pragmas to control overflow and rounding behaviors are not implemented.
-@end itemize
+@cindex designators
+The @samp{[@var{index}]} or @samp{.@var{fieldname}} is known as a
+@dfn{designator}. You can also use a designator (or the obsolete colon
+syntax) when initializing a union, to specify which element of the union
+should be used. For example,
-Fixed-point types are supported by the DWARF debug information format.
+@smallexample
+union foo @{ int i; double d; @};
-@node Aggregate Types
-@section Array, Union, and Struct Extensions
+union foo f = @{ .d = 4 @};
+@end smallexample
-GCC supports several extensions relating to array, union, and struct types,
-including extensions for aggregate initializers for objects of these types.
+@noindent
+converts 4 to a @code{double} to store it in the union using
+the second element. By contrast, casting 4 to type @code{union foo}
+stores it into the union as the integer @code{i}, since it is
+an integer. @xref{Cast to Union}.
-@menu
-* Variable Length:: Arrays whose length is computed at run time.
-* Zero Length:: Zero-length arrays.
-* Empty Structures:: Structures with no members.
-* Flexible Array Members in Unions:: Unions with Flexible Array Members.
-* Flexible Array Members alone in Structures:: Structures with only Flexible Array Members.
-* Unnamed Fields:: Unnamed struct/union fields within structs/unions.
-* Cast to Union:: Casting to union type from any member of the union.
-* Subscripting:: Any array can be subscripted, even if not an lvalue.
-* Initializers:: Non-constant initializers.
-* Compound Literals:: Compound literals give structures, unions
- or arrays as values.
-* Designated Inits:: Labeling elements of initializers.
-@end menu
-
-@node Variable Length
-@subsection Arrays of Variable Length
-@cindex variable-length arrays
-@cindex arrays of variable length
-@cindex VLAs
-
-Variable-length automatic arrays are allowed in ISO C99, and as an
-extension GCC accepts them in C90 mode and in C++. These arrays are
-declared like any other automatic arrays, but with a length that is not
-a constant expression. The storage is allocated at the point of
-declaration and deallocated when the block scope containing the declaration
-exits. For
-example:
+You can combine this technique of naming elements with ordinary C
+initialization of successive elements. Each initializer element that
+does not have a designator applies to the next consecutive element of the
+array or structure. For example,
@smallexample
-FILE *
-concat_fopen (char *s1, char *s2, char *mode)
-@{
- char str[strlen (s1) + strlen (s2) + 1];
- strcpy (str, s1);
- strcat (str, s2);
- return fopen (str, mode);
-@}
+int a[6] = @{ [1] = v1, v2, [4] = v4 @};
@end smallexample
-@cindex scope of a variable length array
-@cindex variable-length array scope
-@cindex deallocating variable length arrays
-Jumping or breaking out of the scope of the array name deallocates the
-storage. Jumping into the scope is not allowed; you get an error
-message for it.
-
-@cindex variable-length array in a structure
-As an extension, GCC accepts variable-length arrays as a member of
-a structure or a union. For example:
+@noindent
+is equivalent to
@smallexample
-void
-foo (int n)
-@{
- struct S @{ int x[n]; @};
-@}
+int a[6] = @{ 0, v1, v2, 0, v4, 0 @};
@end smallexample
-@cindex @code{alloca} vs variable-length arrays
-You can use the function @code{alloca} to get an effect much like
-variable-length arrays. The function @code{alloca} is available in
-many other C implementations (but not in all). On the other hand,
-variable-length arrays are more elegant.
-
-There are other differences between these two methods. Space allocated
-with @code{alloca} exists until the containing @emph{function} returns.
-The space for a variable-length array is deallocated as soon as the array
-name's scope ends, unless you also use @code{alloca} in this scope.
-
-You can also use variable-length arrays as arguments to functions:
+Labeling the elements of an array initializer is especially useful
+when the indices are characters or belong to an @code{enum} type.
+For example:
@smallexample
-struct entry
-tester (int len, char data[len][len])
-@{
- /* @r{@dots{}} */
-@}
+int whitespace[256]
+ = @{ [' '] = 1, ['\t'] = 1, ['\h'] = 1,
+ ['\f'] = 1, ['\n'] = 1, ['\r'] = 1 @};
@end smallexample
-The length of an array is computed once when the storage is allocated
-and is remembered for the scope of the array in case you access it with
-@code{sizeof}.
-
-If you want to pass the array first and the length afterward, you can
-use a forward declaration in the parameter list---another GNU extension.
+@cindex designator lists
+You can also write a series of @samp{.@var{fieldname}} and
+@samp{[@var{index}]} designators before an @samp{=} to specify a
+nested subobject to initialize; the list is taken relative to the
+subobject corresponding to the closest surrounding brace pair. For
+example, with the @samp{struct point} declaration above:
@smallexample
-struct entry
-tester (int len; char data[len][len], int len)
-@{
- /* @r{@dots{}} */
-@}
+struct point ptarray[10] = @{ [2].y = yv2, [2].x = xv2, [0].x = xv0 @};
@end smallexample
-@cindex parameter forward declaration
-The @samp{int len} before the semicolon is a @dfn{parameter forward
-declaration}, and it serves the purpose of making the name @code{len}
-known when the declaration of @code{data} is parsed.
+If the same field is initialized multiple times, or overlapping
+fields of a union are initialized, the value from the last
+initialization is used. When a field of a union is itself a structure,
+the entire structure from the last field initialized is used. If any previous
+initializer has side effect, it is unspecified whether the side effect
+happens or not. Currently, GCC discards the side-effecting
+initializer expressions and issues a warning.
-You can write any number of such parameter forward declarations in the
-parameter list. They can be separated by commas or semicolons, but the
-last one must end with a semicolon, which is followed by the ``real''
-parameter declarations. Each forward declaration must match a ``real''
-declaration in parameter name and data type. ISO C99 does not support
-parameter forward declarations.
+@node Named Address Spaces
+@section Named Address Spaces
+@cindex Named Address Spaces
-@node Zero Length
-@subsection Arrays of Length Zero
-@cindex arrays of length zero
-@cindex zero-length arrays
-@cindex length-zero arrays
-@cindex flexible array members
+As an extension, GNU C supports named address spaces as
+defined in the N1275 draft of ISO/IEC DTR 18037. Support for named
+address spaces in GCC will evolve as the draft technical report
+changes. Calling conventions for any target might also change. At
+present, only the AVR, M32C, PRU, RL78, and x86 targets support
+address spaces other than the generic address space.
-Declaring zero-length arrays is allowed in GNU C as an extension.
-A zero-length array can be useful as the last element of a structure
-that is really a header for a variable-length object:
+Address space identifiers may be used exactly like any other C type
+qualifier (e.g., @code{const} or @code{volatile}). See the N1275
+document for more details.
-@smallexample
-struct line @{
- int length;
- char contents[0];
-@};
+@anchor{AVR Named Address Spaces}
+@subsection AVR Named Address Spaces
-struct line *thisline = (struct line *)
- malloc (sizeof (struct line) + this_length);
-thisline->length = this_length;
-@end smallexample
+On the AVR target, there are several address spaces that can be used
+in order to put read-only data into the flash memory and access that
+data by means of the special instructions @code{LPM} or @code{ELPM}
+needed to read from flash.
-In this example, @code{thisline->contents} is an array of @code{char} that
-can hold up to @code{thisline->length} bytes.
+Devices belonging to @code{avrtiny} and @code{avrxmega3} can access
+flash memory by means of @code{LD*} instructions because the flash
+memory is mapped into the RAM address space. There is @emph{no need}
+for language extensions like @code{__flash} or attribute
+@ref{AVR Variable Attributes,,@code{progmem}}.
+The default linker description files for these devices cater for that
+feature and @code{.rodata} stays in flash: The compiler just generates
+@code{LD*} instructions, and the linker script adds core specific
+offsets to all @code{.rodata} symbols: @code{0x4000} in the case of
+@code{avrtiny} and @code{0x8000} in the case of @code{avrxmega3}.
+See @ref{AVR Options} for a list of respective devices.
-Although the size of a zero-length array is zero, an array member of
-this kind may increase the size of the enclosing type as a result of tail
-padding. The offset of a zero-length array member from the beginning
-of the enclosing structure is the same as the offset of an array with
-one or more elements of the same type. The alignment of a zero-length
-array is the same as the alignment of its elements.
+For devices not in @code{avrtiny} or @code{avrxmega3},
+any data including read-only data is located in RAM (the generic
+address space) because flash memory is not visible in the RAM address
+space. In order to locate read-only data in flash memory @emph{and}
+to generate the right instructions to access this data without
+using (inline) assembler code, special address spaces are needed.
-Declaring zero-length arrays in other contexts, including as interior
-members of structure objects or as non-member objects, is discouraged.
-Accessing elements of zero-length arrays declared in such contexts is
-undefined and may be diagnosed.
+@table @code
+@cindex @code{__flash} AVR Named Address Spaces
+@item __flash
+The @code{__flash} qualifier locates data in the
+@code{.progmem.data} section. Data is read using the @code{LPM}
+instruction. Pointers to this address space are 16 bits wide.
-In the absence of the zero-length array extension, in ISO C90
-the @code{contents} array in the example above would typically be declared
-to have a single element. Unlike a zero-length array which only contributes
-to the size of the enclosing structure for the purposes of alignment,
-a one-element array always occupies at least as much space as a single
-object of the type. Although using one-element arrays this way is
-discouraged, GCC handles accesses to trailing one-element array members
-analogously to zero-length arrays.
+@cindex @code{__flash1} AVR Named Address Spaces
+@cindex @code{__flash2} AVR Named Address Spaces
+@cindex @code{__flash3} AVR Named Address Spaces
+@cindex @code{__flash4} AVR Named Address Spaces
+@cindex @code{__flash5} AVR Named Address Spaces
+@item __flash1
+@itemx __flash2
+@itemx __flash3
+@itemx __flash4
+@itemx __flash5
+These are 16-bit address spaces locating data in section
+@code{.progmem@var{N}.data} where @var{N} refers to
+address space @code{__flash@var{N}}.
+The compiler sets the @code{RAMPZ} segment register appropriately
+before reading data by means of the @code{ELPM} instruction.
-The preferred mechanism to declare variable-length types like
-@code{struct line} above is the ISO C99 @dfn{flexible array member},
-with slightly different syntax and semantics:
+@cindex @code{__flashx} AVR Named Address Spaces
+@item __flashx
-@itemize @bullet
-@item
-Flexible array members are written as @code{contents[]} without
-the @code{0}.
+This is a 24-bit flash address space locating data in section
+@code{.progmemx.data}.
+The compiler sets the @code{RAMPZ} segment register appropriately
+before reading data by means of the @code{ELPM} instruction.
-@item
-Flexible array members have incomplete type, and so the @code{sizeof}
-operator may not be applied. As a quirk of the original implementation
-of zero-length arrays, @code{sizeof} evaluates to zero.
+@cindex @code{__memx} AVR Named Address Spaces
+@item __memx
+This is a 24-bit address space that linearizes flash and RAM:
+If the high bit of the address is set, data is read from
+RAM using the lower two bytes as RAM address.
+If the high bit of the address is clear, data is read from flash
+with @code{RAMPZ} set according to the high byte of the address.
+@xref{AVR Built-in Functions,,@code{__builtin_avr_flash_segment}}.
-@item
-Flexible array members may only appear as the last member of a
-@code{struct} that is otherwise non-empty.
+Objects in this address space are located in @code{.progmemx.data}.
+@end table
-@item
-A structure containing a flexible array member, or a union containing
-such a structure (possibly recursively), may not be a member of a
-structure or an element of an array. (However, these uses are
-permitted by GCC as extensions, see details below.)
-@end itemize
+@b{Example}
-The GCC extension accepts a structure containing an ISO C99 @dfn{flexible array
-member}, or a union containing such a structure (possibly recursively)
-to be a member of a structure.
+@smallexample
+char my_read (const __flash char ** p)
+@{
+ /* p is a pointer to RAM that points to a pointer to flash.
+ The first indirection of p reads that flash pointer
+ from RAM and the second indirection reads a char from this
+ flash address. */
-There are two situations:
+ return **p;
+@}
-@itemize @bullet
-@item
-A structure containing a C99 flexible array member, or a union containing
-such a structure, is the last field of another structure, for example:
+/* Locate array[] in flash memory */
+const __flash int array[] = @{ 3, 5, 7, 11, 13, 17, 19 @};
-@smallexample
-struct flex @{ int length; char data[]; @};
-union union_flex @{ int others; struct flex f; @};
+int i = 1;
-struct out_flex_struct @{ int m; struct flex flex_data; @};
-struct out_flex_union @{ int n; union union_flex flex_data; @};
-@end smallexample
-
-In the above, both @code{out_flex_struct.flex_data.data[]} and
-@code{out_flex_union.flex_data.f.data[]} are considered as flexible arrays too.
-
-@item
-A structure containing a C99 flexible array member, or a union containing
-such a structure, is not the last field of another structure, for example:
-
-@smallexample
-struct flex @{ int length; char data[]; @};
-
-struct mid_flex @{ int m; struct flex flex_data; int n; @};
+int main (void)
+@{
+ /* Return 17 by reading from flash memory */
+ return array[array[i]];
+@}
@end smallexample
-In the above, accessing a member of the array @code{mid_flex.flex_data.data[]}
-might have undefined behavior. Compilers do not handle such a case
-consistently. Any code relying on this case should be modified to ensure
-that flexible array members only end up at the ends of structures.
-
-Please use the warning option @option{-Wflex-array-member-not-at-end} to
-identify all such cases in the source code and modify them. This extension
-is now deprecated.
-@end itemize
+@noindent
+For each named address space supported by avr-gcc there is an equally
+named but uppercase built-in macro defined.
+The purpose is to facilitate testing if respective address space
+support is available or not:
-Non-empty initialization of zero-length
-arrays is treated like any case where there are more initializer
-elements than the array holds, in that a suitable warning about ``excess
-elements in array'' is given, and the excess elements (all of them, in
-this case) are ignored.
+@smallexample
+#ifdef __FLASH
+const __flash int var = 1;
-GCC allows static initialization of flexible array members.
-This is equivalent to defining a new structure containing the original
-structure followed by an array of sufficient size to contain the data.
-E.g.@: in the following, @code{f1} is constructed as if it were declared
-like @code{f2}.
+int read_var (void)
+@{
+ return var;
+@}
+#else
+#include <avr/pgmspace.h> /* From AVR-LibC */
-@smallexample
-struct f1 @{
- int x; int y[];
-@} f1 = @{ 1, @{ 2, 3, 4 @} @};
+const int var PROGMEM = 1;
-struct f2 @{
- struct f1 f1; int data[3];
-@} f2 = @{ @{ 1 @}, @{ 2, 3, 4 @} @};
+int read_var (void)
+@{
+ return (int) pgm_read_word (&var);
+@}
+#endif /* __FLASH */
@end smallexample
@noindent
-The convenience of this extension is that @code{f1} has the desired
-type, eliminating the need to consistently refer to @code{f2.f1}.
-
-This has symmetry with normal static arrays, in that an array of
-unknown size is also written with @code{[]}.
-
-Of course, this extension only makes sense if the extra data comes at
-the end of a top-level object, as otherwise we would be overwriting
-data at subsequent offsets. To avoid undue complication and confusion
-with initialization of deeply nested arrays, we simply disallow any
-non-empty initialization except when the structure is the top-level
-object. For example:
+Notice that attribute @ref{AVR Variable Attributes,,@code{progmem}}
+locates data in flash but
+accesses to these data read from generic address space, i.e.@:
+from RAM,
+so that you need special accessors like @code{pgm_read_byte}
+from @w{@uref{https://avrdudes.github.io/avr-libc/avr-libc-user-manual/,AVR-LibC}}
+together with attribute @code{progmem}.
-@smallexample
-struct foo @{ int x; int y[]; @};
-struct bar @{ struct foo z; @};
+@noindent
+@b{Limitations and Caveats}
-struct foo a = @{ 1, @{ 2, 3, 4 @} @}; // @r{Valid.}
-struct bar b = @{ @{ 1, @{ 2, 3, 4 @} @} @}; // @r{Invalid.}
-struct bar c = @{ @{ 1, @{ @} @} @}; // @r{Valid.}
-struct foo d[1] = @{ @{ 1, @{ 2, 3, 4 @} @} @}; // @r{Invalid.}
-@end smallexample
+@itemize
+@item
+Reading across the 64@tie{}KiB section boundary of
+the @code{__flash} or @code{__flash@var{N}} address spaces
+is not supported. The only address spaces that
+support reading across the 64@tie{}KiB flash segment boundaries are
+@code{__memx} and @code{__flashx}.
-@node Empty Structures
-@subsection Structures with No Members
-@cindex empty structures
-@cindex zero-size structures
+@item
+If you use one of the @code{__flash@var{N}} address spaces
+you must arrange your linker script to locate the
+@code{.progmem@var{N}.data} sections according to your needs.
+For an example, see the
+@w{@uref{https://gcc.gnu.org/wiki/avr-gcc#Address_Spaces,avr-gcc wiki}}
-GCC permits a C structure to have no members:
+@item
+Any data or pointers to the non-generic address spaces must
+be qualified as @code{const}, i.e.@: as read-only data.
+This still applies if the data in one of these address
+spaces like software version number or calibration lookup table are intended to
+be changed after load time by, say, a boot loader. In this case
+the right qualification is @code{const} @code{volatile} so that the compiler
+must not optimize away known values or insert them
+as immediates into operands of instructions.
+@item
+The following code initializes a variable @code{pfoo}
+located in static storage with a 24-bit address:
@smallexample
-struct empty @{
-@};
+extern const __memx char foo;
+const __memx void *pfoo = &foo;
@end smallexample
-The structure has size zero. In C++, empty structures are part
-of the language. G++ treats empty structures as if they had a single
-member of type @code{char}.
-
-@node Flexible Array Members in Unions
-@subsection Unions with Flexible Array Members
-@cindex unions with flexible array members
-@cindex unions with FAMs
+@item
+On the reduced Tiny devices like ATtiny40, no address spaces are supported.
+Just use vanilla C / C++ code without overhead as outlined above.
+Attribute @code{progmem} is supported but works differently,
+see @ref{AVR Variable Attributes}.
-GCC permits a C99 flexible array member (FAM) to be in a union:
+@end itemize
-@smallexample
-union with_fam @{
- int a;
- int b[];
-@};
-@end smallexample
+@subsection M32C Named Address Spaces
+@cindex @code{__far} M32C Named Address Spaces
-If every member of a union is a flexible array member, the size of
-such a union is zero.
+On the M32C target, with the R8C and M16C CPU variants, variables
+qualified with @code{__far} are accessed using 32-bit addresses in
+order to access memory beyond the first 64@tie{}Ki bytes. If
+@code{__far} is used with the M32CM or M32C CPU variants, it has no
+effect.
-@node Flexible Array Members alone in Structures
-@subsection Structures with only Flexible Array Members
-@cindex structures with only flexible array members
-@cindex structures with only FAMs
+@subsection PRU Named Address Spaces
+@cindex @code{__regio_symbol} PRU Named Address Spaces
-GCC permits a C99 flexible array member (FAM) to be alone in a structure:
+On the PRU target, variables qualified with @code{__regio_symbol} are
+aliases used to access the special I/O CPU registers. They must be
+declared as @code{extern} because such variables will not be allocated in
+any data memory. They must also be marked as @code{volatile}, and can
+only be 32-bit integer types. The only names those variables can have
+are @code{__R30} and @code{__R31}, representing respectively the
+@code{R30} and @code{R31} special I/O CPU registers. Hence the following
+example is the only valid usage of @code{__regio_symbol}:
@smallexample
-struct only_fam @{
- int b[];
-@};
+extern volatile __regio_symbol uint32_t __R30;
+extern volatile __regio_symbol uint32_t __R31;
@end smallexample
-The size of such a structure is zero.
-
-@node Unnamed Fields
-@subsection Unnamed Structure and Union Fields
-@cindex @code{struct}
-@cindex @code{union}
+@subsection RL78 Named Address Spaces
+@cindex @code{__far} RL78 Named Address Spaces
-As permitted by ISO C11 and for compatibility with other compilers,
-GCC allows you to define
-a structure or union that contains, as fields, structures and unions
-without names. For example:
+On the RL78 target, variables qualified with @code{__far} are accessed
+with 32-bit pointers (20-bit addresses) rather than the default 16-bit
+addresses. Non-far variables are assumed to appear in the topmost
+64@tie{}KiB of the address space.
-@smallexample
-struct @{
- int a;
- union @{
- int b;
- float c;
- @};
- int d;
-@} foo;
-@end smallexample
+@subsection x86 Named Address Spaces
+@cindex x86 named address spaces
-@noindent
-In this example, you are able to access members of the unnamed
-union with code like @samp{foo.b}. Note that only unnamed structs and
-unions are allowed, you may not have, for example, an unnamed
-@code{int}.
+On the x86 target, variables may be declared as being relative
+to the @code{%fs} or @code{%gs} segments.
-You must never create such structures that cause ambiguous field definitions.
-For example, in this structure:
+@table @code
+@cindex @code{__seg_fs} x86 named address space
+@cindex @code{__seg_gs} x86 named address space
+@item __seg_fs
+@itemx __seg_gs
+The object is accessed with the respective segment override prefix.
-@smallexample
-struct @{
- int a;
- struct @{
- int a;
- @};
-@} foo;
-@end smallexample
+The respective segment base must be set via some method specific to
+the operating system. Rather than require an expensive system call
+to retrieve the segment base, these address spaces are not considered
+to be subspaces of the generic (flat) address space. This means that
+explicit casts are required to convert pointers between these address
+spaces and the generic address space. In practice the application
+should cast to @code{uintptr_t} and apply the segment base offset
+that it installed previously.
-@noindent
-it is ambiguous which @code{a} is being referred to with @samp{foo.a}.
-The compiler gives errors for such constructs.
+The preprocessor symbols @code{__SEG_FS} and @code{__SEG_GS} are
+defined when these address spaces are supported.
+@end table
-@opindex fms-extensions
-Unless @option{-fms-extensions} is used, the unnamed field must be a
-structure or union definition without a tag (for example, @samp{struct
-@{ int a; @};}). If @option{-fms-extensions} is used, the field may
-also be a definition with a tag such as @samp{struct foo @{ int a;
-@};}, a reference to a previously defined structure or union such as
-@samp{struct foo;}, or a reference to a @code{typedef} name for a
-previously defined structure or union type.
+@node Function Attributes
+@section Declaring Attributes of Functions
+@cindex function attributes
+@cindex declaring attributes of functions
-@opindex fplan9-extensions
-The option @option{-fplan9-extensions} enables
-@option{-fms-extensions} as well as two other extensions. First, a
-pointer to a structure is automatically converted to a pointer to an
-anonymous field for assignments and function calls. For example:
+In GNU C and C++, you can use function attributes to specify certain
+function properties that may help the compiler optimize calls or
+check code more carefully for correctness. For example, you
+can use attributes to specify that a function never returns
+(@code{noreturn}), returns a value depending only on the values of
+its arguments (@code{const}), or has @code{printf}-style arguments
+(@code{format}).
-@smallexample
-struct s1 @{ int a; @};
-struct s2 @{ struct s1; @};
-extern void f1 (struct s1 *);
-void f2 (struct s2 *p) @{ f1 (p); @}
-@end smallexample
+You can also use attributes to control memory placement, code
+generation options or call/return conventions within the function
+being annotated. Many of these attributes are target-specific. For
+example, many targets support attributes for defining interrupt
+handler functions, which typically must follow special register usage
+and return conventions. Such attributes are described in the subsection
+for each target. However, a considerable number of attributes are
+supported by most, if not all targets. Those are described in
+the @ref{Common Function Attributes} section.
-@noindent
-In the call to @code{f1} inside @code{f2}, the pointer @code{p} is
-converted into a pointer to the anonymous field.
+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::} prefix on attribute names. Note that the exact rules for
+placement of attributes in your source code are different depending on
+which syntax you use. @xref{Attribute Syntax}, for details.
-Second, when the type of an anonymous field is a @code{typedef} for a
-@code{struct} or @code{union}, code may refer to the field using the
-name of the @code{typedef}.
+Compatible attribute specifications on distinct declarations
+of the same function are merged. An attribute specification that is not
+compatible with attributes already applied to a declaration of the same
+function is ignored with a warning.
-@smallexample
-typedef struct @{ int a; @} s1;
-struct s2 @{ s1; @};
-s1 f1 (struct s2 *p) @{ return p->s1; @}
-@end smallexample
+Some function attributes take one or more arguments that refer to
+the function's parameters by their positions within the function parameter
+list. Such attribute arguments are referred to as @dfn{positional arguments}.
+Unless specified otherwise, positional arguments that specify properties
+of parameters with pointer types can also specify the same properties of
+the implicit C++ @code{this} argument in non-static member functions, and
+of parameters of reference to a pointer type. For ordinary functions,
+position one refers to the first parameter on the list. In C++ non-static
+member functions, position one refers to the implicit @code{this} pointer.
+The same restrictions and effects apply to function attributes used with
+ordinary functions or C++ member functions.
-These usages are only permitted when they are not ambiguous.
+GCC also supports attributes on
+variable declarations (@pxref{Variable Attributes}),
+labels (@pxref{Label Attributes}),
+enumerators (@pxref{Enumerator Attributes}),
+statements (@pxref{Statement Attributes}),
+types (@pxref{Type Attributes}),
+and on field declarations (for @code{tainted_args}).
-@node Cast to Union
-@subsection Cast to a Union Type
-@cindex cast to a union
-@cindex union, casting to a
+There is some overlap between the purposes of attributes and pragmas
+(@pxref{Pragmas,,Pragmas Accepted by GCC}). It has been
+found convenient to use @code{__attribute__} to achieve a natural
+attachment of attributes to their corresponding declarations, whereas
+@code{#pragma} is of use for compatibility with other compilers
+or constructs that do not naturally form part of the grammar.
-A cast to a union type is a C extension not available in C++. It looks
-just like ordinary casts with the constraint that the type specified is
-a union type. You can specify the type either with the @code{union}
-keyword or with a @code{typedef} name that refers to a union. The result
-of a cast to a union is a temporary rvalue of the union type with a member
-whose type matches that of the operand initialized to the value of
-the operand. The effect of a cast to a union is similar to a compound
-literal except that it yields an rvalue like standard casts do.
-@xref{Compound Literals}.
+In addition to the attributes documented here,
+GCC plugins may provide their own attributes.
-Expressions that may be cast to the union type are those whose type matches
-at least one of the members of the union. Thus, given the following union
-and variables:
+@menu
+* Common Function Attributes::
+* AArch64 Function Attributes::
+* AMD GCN Function Attributes::
+* ARC Function Attributes::
+* ARM Function Attributes::
+* AVR Function Attributes::
+* Blackfin Function Attributes::
+* BPF Function Attributes::
+* C-SKY Function Attributes::
+* Epiphany Function Attributes::
+* H8/300 Function Attributes::
+* IA-64 Function Attributes::
+* LoongArch Function Attributes::
+* M32C Function Attributes::
+* M32R/D Function Attributes::
+* m68k Function Attributes::
+* MCORE Function Attributes::
+* MicroBlaze Function Attributes::
+* Microsoft Windows Function Attributes::
+* MIPS Function Attributes::
+* MSP430 Function Attributes::
+* NDS32 Function Attributes::
+* Nvidia PTX Function Attributes::
+* PowerPC Function Attributes::
+* RISC-V Function Attributes::
+* RL78 Function Attributes::
+* RX Function Attributes::
+* S/390 Function Attributes::
+* SH Function Attributes::
+* Symbian OS Function Attributes::
+* V850 Function Attributes::
+* Visium Function Attributes::
+* x86 Function Attributes::
+* Xstormy16 Function Attributes::
+@end menu
-@smallexample
-union foo @{ int i; double d; @};
-int x;
-double y;
-union foo z;
-@end smallexample
+@node Common Function Attributes
+@subsection Common Function Attributes
-@noindent
-both @code{x} and @code{y} can be cast to type @code{union foo} and
-the following assignments
-@smallexample
- z = (union foo) x;
- z = (union foo) y;
-@end smallexample
-are shorthand equivalents of these
-@smallexample
- z = (union foo) @{ .i = x @};
- z = (union foo) @{ .d = y @};
-@end smallexample
+The following attributes are supported on most targets.
-However, @code{(union foo) FLT_MAX;} is not a valid cast because the union
-has no member of type @code{float}.
+@table @code
+@c Keep this table alphabetized by attribute name. Treat _ as space.
-Using the cast as the right-hand side of an assignment to a variable of
-union type is equivalent to storing in a member of the union with
-the same type
+@cindex @code{access} function attribute
+@item access (@var{access-mode}, @var{ref-index})
+@itemx access (@var{access-mode}, @var{ref-index}, @var{size-index})
-@smallexample
-union foo u;
-/* @r{@dots{}} */
-u = (union foo) x @equiv{} u.i = x
-u = (union foo) y @equiv{} u.d = y
-@end smallexample
+The @code{access} attribute enables the detection of invalid or unsafe
+accesses by functions to which they apply or their callers, as well as
+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.
-You can also use the union cast as a function argument:
+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.
-@smallexample
-void hack (union foo);
-/* @r{@dots{}} */
-hack ((union foo) x);
-@end smallexample
+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.
-@node Subscripting
-@subsection Non-Lvalue Arrays May Have Subscripts
-@cindex subscripting
-@cindex arrays, non-lvalue
+The optional @var{size-index} positional argument denotes 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
+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.
-@cindex subscripting and function values
-In ISO C99, arrays that are not lvalues still decay to pointers, and
-may be subscripted, although they may not be modified or used after
-the next sequence point and the unary @samp{&} operator may not be
-applied to them. As an extension, GNU C allows such arrays to be
-subscripted in C90 mode, though otherwise they do not decay to
-pointers outside C99 mode. For example,
-this is valid in GNU C though not valid in C90:
+The @code{read_only} access mode specifies that the pointer to which it
+applies is used to read the referenced object but not write to it. Unless
+the argument specifying the size of the access denoted by @var{size-index}
+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{memcpy} function.
@smallexample
-@group
-struct foo @{int a[4];@};
-
-struct foo f();
+__attribute__ ((access (read_only, 1)))
+int puts (const char*);
-bar (int index)
-@{
- return f().a[index];
-@}
-@end group
+__attribute__ ((access (read_only, 2, 3)))
+void* memcpy (void*, const void*, size_t);
@end smallexample
-@node Initializers
-@subsection Non-Constant Initializers
-@cindex initializers, non-constant
-@cindex non-constant initializers
-
-As in standard C++ and ISO C99, the elements of an aggregate initializer for an
-automatic variable are not required to be constant expressions in GNU C@.
-Here is an example of an initializer with run-time varying elements:
+The @code{read_write} access mode applies to arguments of pointer types
+without the @code{const} qualifier. It specifies that the pointer to which
+it applies is used to both read and write the referenced object. Unless
+the argument specifying the size of the access denoted by @var{size-index}
+is zero, the object referenced by the pointer must be initialized. An example
+of the use of the @code{read_write} access mode is the first argument to
+the @code{strcat} function.
@smallexample
-foo (float f, float g)
-@{
- float beat_freqs[2] = @{ f-g, f+g @};
- /* @r{@dots{}} */
-@}
+__attribute__ ((access (read_write, 1), access (read_only, 2)))
+char* strcat (char*, const char*);
@end smallexample
-@node Compound Literals
-@subsection Compound Literals
-@cindex constructor expressions
-@cindex initializations in expressions
-@cindex structures, constructor expression
-@cindex expressions, constructor
-@cindex compound literals
-@c The GNU C name for what C99 calls compound literals was "constructor expressions".
-
-A compound literal looks like a cast of a brace-enclosed aggregate
-initializer list. Its value is an object of the type specified in
-the cast, containing the elements specified in the initializer.
-Unlike the result of a cast, a compound literal is an lvalue. ISO
-C99 and later support compound literals. As an extension, GCC
-supports compound literals also in C90 mode and in C++, although
-as explained below, the C++ semantics are somewhat different.
-
-Usually, the specified type of a compound literal is a structure. Assume
-that @code{struct foo} and @code{structure} are declared as shown:
-
-@smallexample
-struct foo @{int a; char b[2];@} structure;
-@end smallexample
-
-@noindent
-Here is an example of constructing a @code{struct foo} with a compound literal:
-
-@smallexample
-structure = ((struct foo) @{x + y, 'a', 0@});
-@end smallexample
-
-@noindent
-This is equivalent to writing the following:
+The @code{write_only} access mode applies to arguments of pointer types
+without the @code{const} qualifier. It specifies that the pointer to which
+it applies is used to write to the referenced object but not read from it.
+The object referenced by the pointer need not be initialized. An example
+of the use of the @code{write_only} access mode is the first argument to
+the @code{strcpy} function, or the first two arguments to the @code{fgets}
+function.
@smallexample
-@{
- struct foo temp = @{x + y, 'a', 0@};
- structure = temp;
-@}
-@end smallexample
-
-You can also construct an array, though this is dangerous in C++, as
-explained below. If all the elements of the compound literal are
-(made up of) simple constant expressions suitable for use in
-initializers of objects of static storage duration, then the compound
-literal can be coerced to a pointer to its first element and used in
-such an initializer, as shown here:
+__attribute__ ((access (write_only, 1), access (read_only, 2)))
+char* strcpy (char*, const char*);
-@smallexample
-char **foo = (char *[]) @{ "x", "y", "z" @};
+__attribute__ ((access (write_only, 1, 2), access (read_write, 3)))
+int fgets (char*, int, FILE*);
@end smallexample
-Compound literals for scalar types and union types are also allowed. In
-the following example the variable @code{i} is initialized to the value
-@code{2}, the result of incrementing the unnamed object created by
-the compound literal.
+The access mode @code{none} specifies that the pointer 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
+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.
+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}.
-@smallexample
-int i = ++(int) @{ 1 @};
-@end smallexample
+Note that the @code{access} attribute merely specifies how an object
+referenced by the pointer argument can be accessed; it does not imply that
+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
+caveats.
-As a GNU extension, GCC allows initialization of objects with static storage
-duration by compound literals (which is not possible in ISO C99 because
-the initializer is not a constant).
-It is handled as if the object were initialized only with the brace-enclosed
-list if the types of the compound literal and the object match.
-The elements of the compound literal must be constant.
-If the object being initialized has array type of unknown size, the size is
-determined by the size of the compound literal.
+@cindex @code{alias} function attribute
+@item alias ("@var{target}")
+The @code{alias} attribute causes the declaration to be emitted as an alias
+for another symbol, which must have been previously declared with the same
+type, and for variables, also the same size and alignment. Declaring an alias
+with a different type than the target is undefined and may be diagnosed. As
+an example, the following declarations:
@smallexample
-static struct foo x = (struct foo) @{1, 'a', 'b'@};
-static int y[] = (int []) @{1, 2, 3@};
-static int z[] = (int [3]) @{1@};
+void __f () @{ /* @r{Do something.} */; @}
+void f () __attribute__ ((weak, alias ("__f")));
@end smallexample
@noindent
-The above lines are equivalent to the following:
-@smallexample
-static struct foo x = @{1, 'a', 'b'@};
-static int y[] = @{1, 2, 3@};
-static int z[] = @{1, 0, 0@};
-@end smallexample
+define @samp{f} to be a weak alias for @samp{__f}. In C++, the mangled name
+for the target must be used. It is an error if @samp{__f} is not defined in
+the same translation unit.
-In C, a compound literal designates an unnamed object with static or
-automatic storage duration. In C++, a compound literal designates a
-temporary object that only lives until the end of its full-expression.
-As a result, well-defined C code that takes the address of a subobject
-of a compound literal can be undefined in C++, so G++ rejects
-the conversion of a temporary array to a pointer. For instance, if
-the array compound literal example above appeared inside a function,
-any subsequent use of @code{foo} in C++ would have undefined behavior
-because the lifetime of the array ends after the declaration of @code{foo}.
+This attribute requires assembler and object file support,
+and may not be available on all targets.
-As an optimization, G++ sometimes gives array compound literals longer
-lifetimes: when the array either appears outside a function or has
-a @code{const}-qualified type. If @code{foo} and its initializer had
-elements of type @code{char *const} rather than @code{char *}, or if
-@code{foo} were a global variable, the array would have static storage
-duration. But it is probably safest just to avoid the use of array
-compound literals in C++ code.
+@cindex @code{aligned} function attribute
+@item aligned
+@itemx aligned (@var{alignment})
+The @code{aligned} attribute specifies a minimum alignment for
+the first instruction of the function, measured in bytes. When specified,
+@var{alignment} must be an integer constant power of 2. Specifying no
+@var{alignment} argument implies the ideal alignment for the target.
+The @code{__alignof__} operator can be used to determine what that is
+(@pxref{Alignment}). The attribute has no effect when a definition for
+the function is not provided in the same translation unit.
-@node Designated Inits
-@subsection Designated Initializers
-@cindex initializers with labeled elements
-@cindex labeled elements in initializers
-@cindex case labels in initializers
-@cindex designated initializers
+The attribute cannot be used to decrease the alignment of a function
+previously declared with a more restrictive alignment; only to increase
+it. Attempts to do otherwise are diagnosed. Some targets specify
+a minimum default alignment for functions that is greater than 1. On
+such targets, specifying a less restrictive alignment is silently ignored.
+Using the attribute overrides the effect of the @option{-falign-functions}
+(@pxref{Optimize Options}) option for this function.
-Standard C90 requires the elements of an initializer to appear in a fixed
-order, the same as the order of the elements in the array or structure
-being initialized.
+Note that the effectiveness of @code{aligned} attributes may be
+limited by inherent limitations in the system linker
+and/or object file format. On some systems, the
+linker is only able to arrange for functions to be aligned up to a
+certain maximum alignment. (For some linkers, the maximum supported
+alignment may be very very small.) See your linker documentation for
+further information.
-In ISO C99 you can give the elements in any order, specifying the array
-indices or structure field names they apply to, and GNU C allows this as
-an extension in C90 mode as well. This extension is not
-implemented in GNU C++.
+The @code{aligned} attribute can also be used for variables and fields
+(@pxref{Variable Attributes}.)
-To specify an array index, write
-@samp{[@var{index}] =} before the element value. For example,
+@cindex @code{alloc_align} function attribute
+@item alloc_align (@var{position})
+The @code{alloc_align} attribute may be applied to a function that
+returns a pointer and takes at least one argument of an integer or
+enumerated type.
+It indicates that the returned pointer is aligned on a boundary given
+by the function argument at @var{position}. Meaningful alignments are
+powers of 2 greater than one. GCC uses this information to improve
+pointer alignment analysis.
-@smallexample
-int a[6] = @{ [4] = 29, [2] = 15 @};
-@end smallexample
+The function parameter denoting the allocated alignment is specified by
+one constant integer argument whose number is the argument of the attribute.
+Argument numbering starts at one.
-@noindent
-is equivalent to
+For instance,
@smallexample
-int a[6] = @{ 0, 0, 15, 0, 29, 0 @};
+void* my_memalign (size_t, size_t) __attribute__ ((alloc_align (1)));
@end smallexample
@noindent
-The index values must be constant expressions, even if the array being
-initialized is automatic.
+declares that @code{my_memalign} returns memory with minimum alignment
+given by parameter 1.
-An alternative syntax for this that has been obsolete since GCC 2.5 but
-GCC still accepts is to write @samp{[@var{index}]} before the element
-value, with no @samp{=}.
+@cindex @code{alloc_size} function attribute
+@item alloc_size (@var{position})
+@itemx alloc_size (@var{position-1}, @var{position-2})
+The @code{alloc_size} attribute may be applied to a function that
+returns a pointer and takes at least one argument of an integer or
+enumerated type.
+It indicates that the returned pointer points to memory whose size is
+given by the function argument at @var{position-1}, or by the product
+of the arguments at @var{position-1} and @var{position-2}. Meaningful
+sizes are positive values less than @code{PTRDIFF_MAX}. GCC uses this
+information to improve the results of @code{__builtin_object_size}.
-To initialize a range of elements to the same value, write
-@samp{[@var{first} ... @var{last}] = @var{value}}. This is a GNU
-extension. For example,
+The function parameter(s) denoting the allocated size are specified by
+one or two integer arguments supplied to the attribute. The allocated size
+is either the value of the single function argument specified or the product
+of the two function arguments specified. Argument numbering starts at
+one for ordinary functions, and at two for C++ non-static member functions.
+
+For instance,
@smallexample
-int widths[] = @{ [0 ... 9] = 1, [10 ... 99] = 2, [100] = 3 @};
+void* my_calloc (size_t, size_t) __attribute__ ((alloc_size (1, 2)));
+void* my_realloc (void*, size_t) __attribute__ ((alloc_size (2)));
@end smallexample
@noindent
-If the value in it has side effects, the side effects happen only once,
-not for each initialized field by the range initializer.
+declares that @code{my_calloc} returns memory of the size given by
+the product of parameter 1 and 2 and that @code{my_realloc} returns memory
+of the size given by parameter 2.
-@noindent
-Note that the length of the array is the highest value specified
-plus one.
+@cindex @code{always_inline} function attribute
+@item always_inline
+Generally, functions are not inlined unless optimization is specified.
+For functions declared inline, this attribute inlines the function
+independent of any restrictions that otherwise apply to inlining.
+Failure to inline such a function is diagnosed as an error.
+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.
-In a structure initializer, specify the name of a field to initialize
-with @samp{.@var{fieldname} =} before the element value. For example,
-given the following structure,
+@cindex @code{artificial} function attribute
+@item artificial
+This attribute is useful for small inline wrappers that if possible
+should appear during debugging as a unit. Depending on the debug
+info format it either means marking the function as artificial
+or using the caller location for all instructions within the inlined
+body.
-@smallexample
-struct point @{ int x, y; @};
-@end smallexample
+@cindex @code{assume_aligned} function attribute
+@item assume_aligned (@var{alignment})
+@itemx assume_aligned (@var{alignment}, @var{offset})
+The @code{assume_aligned} attribute may be applied to a function that
+returns a pointer. It indicates that the returned pointer is aligned
+on a boundary given by @var{alignment}. If the attribute has two
+arguments, the second argument is misalignment @var{offset}. Meaningful
+values of @var{alignment} are powers of 2 greater than one. Meaningful
+values of @var{offset} are greater than zero and less than @var{alignment}.
-@noindent
-the following initialization
+For instance
@smallexample
-struct point p = @{ .y = yvalue, .x = xvalue @};
+void* my_alloc1 (size_t) __attribute__((assume_aligned (16)));
+void* my_alloc2 (size_t) __attribute__((assume_aligned (32, 8)));
@end smallexample
@noindent
-is equivalent to
-
-@smallexample
-struct point p = @{ xvalue, yvalue @};
-@end smallexample
+declares that @code{my_alloc1} returns 16-byte aligned pointers and
+that @code{my_alloc2} returns a pointer whose value modulo 32 is equal
+to 8.
-Another syntax that has the same meaning, obsolete since GCC 2.5, is
-@samp{@var{fieldname}:}, as shown here:
+@cindex @code{cold} function attribute
+@item cold
+The @code{cold} attribute on functions is used to inform the compiler that
+the function is unlikely to be executed. The function is optimized for
+size rather than speed and on many targets it is placed into a special
+subsection of the text section so all cold functions appear close together,
+improving code locality of non-cold parts of program. The paths leading
+to calls of cold functions within code are marked as unlikely by the branch
+prediction mechanism. It is thus useful to mark functions used to handle
+unlikely conditions, such as @code{perror}, as cold to improve optimization
+of hot functions that do call marked functions in rare occasions. In C++,
+the @code{cold} attribute can be applied to types with the effect of being
+propagated to member functions. See
+@ref{C++ Attributes}.
-@smallexample
-struct point p = @{ y: yvalue, x: xvalue @};
-@end smallexample
+When profile feedback is available, via @option{-fprofile-use}, cold functions
+are automatically detected and this attribute is ignored.
-Omitted fields are implicitly initialized the same as for objects
-that have static storage duration.
+@cindex @code{const} function attribute
+@cindex functions that have no side effects
+@item const
+Calls to functions whose return value is not affected by changes to
+the observable state of the program and that have no observable effects
+on such state other than to return a value may lend themselves to
+optimizations such as common subexpression elimination. Declaring such
+functions with the @code{const} attribute allows GCC to avoid emitting
+some calls in repeated invocations of the function with the same argument
+values.
-@cindex designators
-The @samp{[@var{index}]} or @samp{.@var{fieldname}} is known as a
-@dfn{designator}. You can also use a designator (or the obsolete colon
-syntax) when initializing a union, to specify which element of the union
-should be used. For example,
+For example,
@smallexample
-union foo @{ int i; double d; @};
-
-union foo f = @{ .d = 4 @};
+int square (int) __attribute__ ((const));
@end smallexample
@noindent
-converts 4 to a @code{double} to store it in the union using
-the second element. By contrast, casting 4 to type @code{union foo}
-stores it into the union as the integer @code{i}, since it is
-an integer. @xref{Cast to Union}.
+tells GCC that subsequent calls to function @code{square} with the same
+argument value can be replaced by the result of the first call regardless
+of the statements in between.
-You can combine this technique of naming elements with ordinary C
-initialization of successive elements. Each initializer element that
-does not have a designator applies to the next consecutive element of the
-array or structure. For example,
+The @code{const} attribute prohibits a function from reading objects
+that affect its return value between successive invocations. However,
+functions declared with the attribute can safely read objects that do
+not change their return value, such as non-volatile constants.
-@smallexample
-int a[6] = @{ [1] = v1, v2, [4] = v4 @};
-@end smallexample
+The @code{const} attribute imposes greater restrictions on a function's
+definition than the similar @code{pure} attribute. Declaring the same
+function with both the @code{const} and the @code{pure} attribute is
+diagnosed. Because a const function cannot have any observable side
+effects it does not make sense for it to return @code{void}. Declaring
+such a function is diagnosed.
-@noindent
-is equivalent to
+@cindex pointer arguments
+Note that a function that has pointer arguments and examines the data
+pointed to must @emph{not} be declared @code{const} if the pointed-to
+data might change between successive invocations of the function. In
+general, since a function cannot distinguish data that might change
+from data that cannot, const functions should never take pointer or,
+in C++, reference arguments. Likewise, a function that calls a non-const
+function usually must not be const itself.
-@smallexample
-int a[6] = @{ 0, v1, v2, 0, v4, 0 @};
-@end smallexample
+@cindex @code{constructor} function attribute
+@cindex @code{destructor} function attribute
+@item constructor
+@itemx destructor
+@itemx constructor (@var{priority})
+@itemx destructor (@var{priority})
+The @code{constructor} attribute causes the function to be called
+automatically before execution enters @code{main ()}. Similarly, the
+@code{destructor} attribute causes the function to be called
+automatically after @code{main ()} completes or @code{exit ()} is
+called. Functions with these attributes are useful for
+initializing data that is used implicitly during the execution of
+the program.
-Labeling the elements of an array initializer is especially useful
-when the indices are characters or belong to an @code{enum} type.
-For example:
+On some 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
+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.
+
+@cindex @code{copy} function attribute
+@item copy
+@itemx copy (@var{function})
+The @code{copy} attribute applies the set of attributes with which
+@var{function} has been declared to the declaration of the function
+to which the attribute is applied. The attribute is designed for
+libraries that define aliases or function resolvers that are expected
+to specify the same set of attributes as their targets. The @code{copy}
+attribute can be used with functions, variables, or types. However,
+the kind of symbol to which the attribute is applied (either function
+or variable) must match the kind of symbol to which the argument refers.
+The @code{copy} attribute copies only syntactic and semantic attributes
+but not attributes that affect a symbol's linkage or visibility such as
+@code{alias}, @code{visibility}, or @code{weak}. The @code{deprecated}
+and @code{target_clones} attribute are also not copied.
+@xref{Common Type Attributes}.
+@xref{Common Variable Attributes}.
+
+For example, the @var{StrongAlias} macro below makes use of the @code{alias}
+and @code{copy} attributes to define an alias named @var{alloc} for function
+@var{allocate} declared with attributes @var{alloc_size}, @var{malloc}, and
+@var{nothrow}. Thanks to the @code{__typeof__} operator the alias has
+the same type as the target function. As a result of the @code{copy}
+attribute the alias also shares the same attributes as the target.
@smallexample
-int whitespace[256]
- = @{ [' '] = 1, ['\t'] = 1, ['\h'] = 1,
- ['\f'] = 1, ['\n'] = 1, ['\r'] = 1 @};
+#define StrongAlias(TargetFunc, AliasDecl) \
+ extern __typeof__ (TargetFunc) AliasDecl \
+ __attribute__ ((alias (#TargetFunc), copy (TargetFunc)));
+
+extern __attribute__ ((alloc_size (1), malloc, nothrow))
+ void* allocate (size_t);
+StrongAlias (allocate, alloc);
@end smallexample
-@cindex designator lists
-You can also write a series of @samp{.@var{fieldname}} and
-@samp{[@var{index}]} designators before an @samp{=} to specify a
-nested subobject to initialize; the list is taken relative to the
-subobject corresponding to the closest surrounding brace pair. For
-example, with the @samp{struct point} declaration above:
+@cindex @code{deprecated} function attribute
+@item deprecated
+@itemx deprecated (@var{msg})
+The @code{deprecated} attribute results in a warning if the function
+is used anywhere in the source file. This is useful when identifying
+functions that are expected to be removed in a future version of a
+program. The warning also includes the location of the declaration
+of the deprecated function, to enable users to easily find further
+information about why the function is deprecated, or what they should
+do instead. Note that the warnings only occurs for uses:
@smallexample
-struct point ptarray[10] = @{ [2].y = yv2, [2].x = xv2, [0].x = xv0 @};
+int old_fn () __attribute__ ((deprecated));
+int old_fn ();
+int (*fn_ptr)() = old_fn;
@end smallexample
-If the same field is initialized multiple times, or overlapping
-fields of a union are initialized, the value from the last
-initialization is used. When a field of a union is itself a structure,
-the entire structure from the last field initialized is used. If any previous
-initializer has side effect, it is unspecified whether the side effect
-happens or not. Currently, GCC discards the side-effecting
-initializer expressions and issues a warning.
+@noindent
+results in a warning on line 3 but not line 2. The optional @var{msg}
+argument, which must be a string, is printed in the warning if
+present.
-@node Hex Floats
-@section Hex Floats
-@cindex hex floats
+The @code{deprecated} attribute can also be used for variables and
+types (@pxref{Variable Attributes}, @pxref{Type Attributes}.)
-ISO C99 and ISO C++17 support floating-point numbers written not only in
-the usual decimal notation, such as @code{1.55e1}, but also numbers such as
-@code{0x1.fp3} written in hexadecimal format. As a GNU extension, GCC
-supports this in C90 mode (except in some cases when strictly
-conforming) and in C++98, C++11 and C++14 modes. In that format the
-@samp{0x} hex introducer and the @samp{p} or @samp{P} exponent field are
-mandatory. The exponent is a decimal number that indicates the power of
-2 by which the significant part is multiplied. Thus @samp{0x1.f} is
-@tex
-$1 {15\over16}$,
-@end tex
-@ifnottex
-1 15/16,
-@end ifnottex
-@samp{p3} multiplies it by 8, and the value of @code{0x1.fp3}
-is the same as @code{1.55e1}.
+The message attached to the attribute is affected by the setting of
+the @option{-fmessage-length} option.
-Unlike for floating-point numbers in the decimal notation the exponent
-is always required in the hexadecimal notation. Otherwise the compiler
-would not be able to resolve the ambiguity of, e.g., @code{0x1.f}. This
-could mean @code{1.0f} or @code{1.9375} since @samp{f} is also the
-extension for floating-point constants of type @code{float}.
+@cindex @code{error} function attribute
+@cindex @code{warning} function attribute
+@item error ("@var{message}")
+@itemx warning ("@var{message}")
+If the @code{error} or @code{warning} attribute
+is used on a function declaration and a call to such a function
+is not eliminated through dead code elimination or other optimizations,
+an error or warning (respectively) that includes @var{message} is diagnosed.
+This is useful
+for compile-time checking, especially together with @code{__builtin_constant_p}
+and inline functions where checking the inline function arguments is not
+possible through @code{extern char [(condition) ? 1 : -1];} tricks.
-@node Named Address Spaces
-@section Named Address Spaces
-@cindex Named Address Spaces
+While it is possible to leave the function undefined and thus invoke
+a link failure (to define the function with
+a message in @code{.gnu.warning*} section),
+when using these attributes the problem is diagnosed
+earlier and with exact location of the call even in presence of inline
+functions or when not emitting debugging information.
-As an extension, GNU C supports named address spaces as
-defined in the N1275 draft of ISO/IEC DTR 18037. Support for named
-address spaces in GCC will evolve as the draft technical report
-changes. Calling conventions for any target might also change. At
-present, only the AVR, M32C, PRU, RL78, and x86 targets support
-address spaces other than the generic address space.
+@cindex @code{expected_throw} function attribute
+@item expected_throw
+This attribute, attached to a function, tells the compiler the function
+is more likely to raise or propagate an exception than to return, loop
+forever, or terminate the program.
-Address space identifiers may be used exactly like any other C type
-qualifier (e.g., @code{const} or @code{volatile}). See the N1275
-document for more details.
+This hint is mostly ignored by the compiler. The only effect is when
+it's applied to @code{noreturn} functions and
+@samp{-fharden-control-flow-redundancy} is enabled, and
+@samp{-fhardcfr-check-noreturn-calls=not-always} is not overridden.
-@anchor{AVR Named Address Spaces}
-@subsection AVR Named Address Spaces
-
-On the AVR target, there are several address spaces that can be used
-in order to put read-only data into the flash memory and access that
-data by means of the special instructions @code{LPM} or @code{ELPM}
-needed to read from flash.
+@cindex @code{externally_visible} function attribute
+@item externally_visible
+This attribute, attached to a global variable or function, nullifies
+the effect of the @option{-fwhole-program} command-line option, so the
+object remains visible outside the current compilation unit.
-Devices belonging to @code{avrtiny} and @code{avrxmega3} can access
-flash memory by means of @code{LD*} instructions because the flash
-memory is mapped into the RAM address space. There is @emph{no need}
-for language extensions like @code{__flash} or attribute
-@ref{AVR Variable Attributes,,@code{progmem}}.
-The default linker description files for these devices cater for that
-feature and @code{.rodata} stays in flash: The compiler just generates
-@code{LD*} instructions, and the linker script adds core specific
-offsets to all @code{.rodata} symbols: @code{0x4000} in the case of
-@code{avrtiny} and @code{0x8000} in the case of @code{avrxmega3}.
-See @ref{AVR Options} for a list of respective devices.
+If @option{-fwhole-program} is used together with @option{-flto} and
+@command{gold} is used as the linker plugin,
+@code{externally_visible} attributes are automatically added to functions
+(not variable yet due to a current @command{gold} issue)
+that are accessed outside of LTO objects according to resolution file
+produced by @command{gold}.
+For other linkers that cannot generate resolution file,
+explicit @code{externally_visible} attributes are still necessary.
-For devices not in @code{avrtiny} or @code{avrxmega3},
-any data including read-only data is located in RAM (the generic
-address space) because flash memory is not visible in the RAM address
-space. In order to locate read-only data in flash memory @emph{and}
-to generate the right instructions to access this data without
-using (inline) assembler code, special address spaces are needed.
+@cindex @code{fd_arg} function attribute
+@item fd_arg
+@itemx fd_arg (@var{N})
+The @code{fd_arg} attribute may be applied to a function that takes an open
+file descriptor at referenced argument @var{N}.
-@table @code
-@cindex @code{__flash} AVR Named Address Spaces
-@item __flash
-The @code{__flash} qualifier locates data in the
-@code{.progmem.data} section. Data is read using the @code{LPM}
-instruction. Pointers to this address space are 16 bits wide.
+It indicates that the passed filedescriptor must not have been closed.
+Therefore, when the analyzer is enabled with @option{-fanalyzer}, the
+analyzer may emit a @option{-Wanalyzer-fd-use-after-close} diagnostic
+if it detects a code path in which a function with this attribute is
+called with a closed file descriptor.
-@cindex @code{__flash1} AVR Named Address Spaces
-@cindex @code{__flash2} AVR Named Address Spaces
-@cindex @code{__flash3} AVR Named Address Spaces
-@cindex @code{__flash4} AVR Named Address Spaces
-@cindex @code{__flash5} AVR Named Address Spaces
-@item __flash1
-@itemx __flash2
-@itemx __flash3
-@itemx __flash4
-@itemx __flash5
-These are 16-bit address spaces locating data in section
-@code{.progmem@var{N}.data} where @var{N} refers to
-address space @code{__flash@var{N}}.
-The compiler sets the @code{RAMPZ} segment register appropriately
-before reading data by means of the @code{ELPM} instruction.
+The attribute also indicates that the file descriptor must have been checked for
+validity before usage. Therefore, analyzer may emit
+@option{-Wanalyzer-fd-use-without-check} diagnostic if it detects a code path in
+which a function with this attribute is called with a file descriptor that has
+not been checked for validity.
-@cindex @code{__flashx} AVR Named Address Spaces
-@item __flashx
+@cindex @code{fd_arg_read} function attribute
+@item fd_arg_read
+@itemx fd_arg_read (@var{N})
+The @code{fd_arg_read} is identical to @code{fd_arg}, but with the additional
+requirement that it might read from the file descriptor, and thus, the file
+descriptor must not have been opened as write-only.
-This is a 24-bit flash address space locating data in section
-@code{.progmemx.data}.
-The compiler sets the @code{RAMPZ} segment register appropriately
-before reading data by means of the @code{ELPM} instruction.
+The analyzer may emit a @option{-Wanalyzer-access-mode-mismatch}
+diagnostic if it detects a code path in which a function with this
+attribute is called on a file descriptor opened with @code{O_WRONLY}.
-@cindex @code{__memx} AVR Named Address Spaces
-@item __memx
-This is a 24-bit address space that linearizes flash and RAM:
-If the high bit of the address is set, data is read from
-RAM using the lower two bytes as RAM address.
-If the high bit of the address is clear, data is read from flash
-with @code{RAMPZ} set according to the high byte of the address.
-@xref{AVR Built-in Functions,,@code{__builtin_avr_flash_segment}}.
+@cindex @code{fd_arg_write} function attribute
+@item fd_arg_write
+@itemx fd_arg_write (@var{N})
+The @code{fd_arg_write} is identical to @code{fd_arg_read} except that the
+analyzer may emit a @option{-Wanalyzer-access-mode-mismatch} diagnostic if
+it detects a code path in which a function with this attribute is called on a
+file descriptor opened with @code{O_RDONLY}.
-Objects in this address space are located in @code{.progmemx.data}.
-@end table
+@cindex @code{flatten} function attribute
+@item flatten
+Generally, inlining into a function is limited. For a function marked with
+this attribute, every call inside this function is inlined including the
+calls such inlining introduces to the function (but not recursive calls
+to the function itself), if possible.
+Functions declared with attribute @code{noinline} and similar are not
+inlined. Whether the function itself is considered for inlining depends
+on its size and the current inlining parameters.
-@b{Example}
+@cindex @code{format} function attribute
+@cindex functions with @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} style arguments
+@opindex Wformat
+@item format (@var{archetype}, @var{string-index}, @var{first-to-check})
+The @code{format} attribute specifies that a function takes @code{printf},
+@code{scanf}, @code{strftime} or @code{strfmon} style arguments that
+should be type-checked against a format string. For example, the
+declaration:
@smallexample
-char my_read (const __flash char ** p)
-@{
- /* p is a pointer to RAM that points to a pointer to flash.
- The first indirection of p reads that flash pointer
- from RAM and the second indirection reads a char from this
- flash address. */
-
- return **p;
-@}
+extern int
+my_printf (void *my_object, const char *my_format, ...)
+ __attribute__ ((format (printf, 2, 3)));
+@end smallexample
-/* Locate array[] in flash memory */
-const __flash int array[] = @{ 3, 5, 7, 11, 13, 17, 19 @};
+@noindent
+causes the compiler to check the arguments in calls to @code{my_printf}
+for consistency with the @code{printf} style format string argument
+@code{my_format}.
-int i = 1;
+The parameter @var{archetype} determines how the format string is
+interpreted, and should be @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.
+@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
+@file{msvcrt.dll} library.
+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
+argument to check against the format string. For functions
+where the arguments are not available to be checked (such as
+@code{vprintf}), specify the third parameter as zero. In this case the
+compiler only checks the format string for consistency. For
+@code{strftime} formats, the third parameter is required to be zero.
+Since non-static C++ methods have an implicit @code{this} argument, the
+arguments of such methods should be counted from two, not one, when
+giving values for @var{string-index} and @var{first-to-check}.
-int main (void)
-@{
- /* Return 17 by reading from flash memory */
- return array[array[i]];
-@}
-@end smallexample
+In the example above, the format string (@code{my_format}) is the second
+argument of the function @code{my_print}, and the arguments to check
+start with the third argument, so the correct parameters for the format
+attribute are 2 and 3.
-@noindent
-For each named address space supported by avr-gcc there is an equally
-named but uppercase built-in macro defined.
-The purpose is to facilitate testing if respective address space
-support is available or not:
+@opindex ffreestanding
+@opindex fno-builtin
+The @code{format} attribute allows you to identify your own functions
+that take format strings as arguments, so that GCC can check the
+calls to these functions for errors. The compiler always (unless
+@option{-ffreestanding} or @option{-fno-builtin} is used) checks formats
+for the standard library functions @code{printf}, @code{fprintf},
+@code{sprintf}, @code{scanf}, @code{fscanf}, @code{sscanf}, @code{strftime},
+@code{vprintf}, @code{vfprintf} and @code{vsprintf} whenever such
+warnings are requested (using @option{-Wformat}), so there is no need to
+modify the header file @file{stdio.h}. In C99 mode, the functions
+@code{snprintf}, @code{vsnprintf}, @code{vscanf}, @code{vfscanf} and
+@code{vsscanf} are also checked. Except in strictly conforming C
+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}.
-@smallexample
-#ifdef __FLASH
-const __flash int var = 1;
+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.
-int read_var (void)
-@{
- return var;
-@}
-#else
-#include <avr/pgmspace.h> /* From AVR-LibC */
+The target may also provide additional types of format checks.
+@xref{Target Format Checks,,Format Checks Specific to Particular
+Target Machines}.
-const int var PROGMEM = 1;
+@cindex @code{format_arg} function attribute
+@opindex Wformat-nonliteral
+@item format_arg (@var{string-index})
+The @code{format_arg} attribute specifies that a function takes one or
+more format strings for a @code{printf}, @code{scanf}, @code{strftime} or
+@code{strfmon} style function and modifies it (for example, to translate
+it into another language), so the result can be passed to a
+@code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} style
+function (with the remaining arguments to the format function the same
+as they would have been for the unmodified string). Multiple
+@code{format_arg} attributes may be applied to the same function, each
+designating a distinct parameter as a format string. For example, the
+declaration:
-int read_var (void)
-@{
- return (int) pgm_read_word (&var);
-@}
-#endif /* __FLASH */
+@smallexample
+extern char *
+my_dgettext (char *my_domain, const char *my_format)
+ __attribute__ ((format_arg (2)));
@end smallexample
@noindent
-Notice that attribute @ref{AVR Variable Attributes,,@code{progmem}}
-locates data in flash but
-accesses to these data read from generic address space, i.e.@:
-from RAM,
-so that you need special accessors like @code{pgm_read_byte}
-from @w{@uref{https://avrdudes.github.io/avr-libc/avr-libc-user-manual/,AVR-LibC}}
-together with attribute @code{progmem}.
-
-@noindent
-@b{Limitations and Caveats}
+causes the compiler to check the arguments in calls to a @code{printf},
+@code{scanf}, @code{strftime} or @code{strfmon} type function, whose
+format string argument is a call to the @code{my_dgettext} function, for
+consistency with the format string argument @code{my_format}. If the
+@code{format_arg} attribute had not been specified, all the compiler
+could tell in such calls to format functions would be that the format
+string argument is not constant; this would generate a warning when
+@option{-Wformat-nonliteral} is used, but the calls could not be checked
+without the attribute.
-@itemize
-@item
-Reading across the 64@tie{}KiB section boundary of
-the @code{__flash} or @code{__flash@var{N}} address spaces
-is not supported. The only address spaces that
-support reading across the 64@tie{}KiB flash segment boundaries are
-@code{__memx} and @code{__flashx}.
-
-@item
-If you use one of the @code{__flash@var{N}} address spaces
-you must arrange your linker script to locate the
-@code{.progmem@var{N}.data} sections according to your needs.
-For an example, see the
-@w{@uref{https://gcc.gnu.org/wiki/avr-gcc#Address_Spaces,avr-gcc wiki}}
-
-@item
-Any data or pointers to the non-generic address spaces must
-be qualified as @code{const}, i.e.@: as read-only data.
-This still applies if the data in one of these address
-spaces like software version number or calibration lookup table are intended to
-be changed after load time by, say, a boot loader. In this case
-the right qualification is @code{const} @code{volatile} so that the compiler
-must not optimize away known values or insert them
-as immediates into operands of instructions.
-
-@item
-The following code initializes a variable @code{pfoo}
-located in static storage with a 24-bit address:
-@smallexample
-extern const __memx char foo;
-const __memx void *pfoo = &foo;
-@end smallexample
-
-@item
-On the reduced Tiny devices like ATtiny40, no address spaces are supported.
-Just use vanilla C / C++ code without overhead as outlined above.
-Attribute @code{progmem} is supported but works differently,
-see @ref{AVR Variable Attributes}.
-
-@end itemize
-
-@subsection M32C Named Address Spaces
-@cindex @code{__far} M32C Named Address Spaces
-
-On the M32C target, with the R8C and M16C CPU variants, variables
-qualified with @code{__far} are accessed using 32-bit addresses in
-order to access memory beyond the first 64@tie{}Ki bytes. If
-@code{__far} is used with the M32CM or M32C CPU variants, it has no
-effect.
+In calls to a function declared with more than one @code{format_arg}
+attribute, each with a distinct argument value, the corresponding
+actual function arguments are checked against all format strings
+designated by the attributes. This capability is designed to support
+the GNU @code{ngettext} family of functions.
-@subsection PRU Named Address Spaces
-@cindex @code{__regio_symbol} PRU Named Address Spaces
+The parameter @var{string-index} specifies which argument is the format
+string argument (starting from one). Since non-static C++ methods have
+an implicit @code{this} argument, the arguments of such methods should
+be counted from two.
-On the PRU target, variables qualified with @code{__regio_symbol} are
-aliases used to access the special I/O CPU registers. They must be
-declared as @code{extern} because such variables will not be allocated in
-any data memory. They must also be marked as @code{volatile}, and can
-only be 32-bit integer types. The only names those variables can have
-are @code{__R30} and @code{__R31}, representing respectively the
-@code{R30} and @code{R31} special I/O CPU registers. Hence the following
-example is the only valid usage of @code{__regio_symbol}:
+The @code{format_arg} attribute allows you to identify your own
+functions that modify format strings, so that GCC can check the
+calls to @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon}
+type function whose operands are a call to one of your own function.
+The compiler always treats @code{gettext}, @code{dgettext}, and
+@code{dcgettext} in this manner except when strict ISO C support is
+requested by @option{-ansi} or an appropriate @option{-std} option, or
+@option{-ffreestanding} or @option{-fno-builtin}
+is used. @xref{C Dialect Options,,Options
+Controlling C Dialect}.
-@smallexample
-extern volatile __regio_symbol uint32_t __R30;
-extern volatile __regio_symbol uint32_t __R31;
-@end smallexample
+For Objective-C dialects, the @code{format-arg} attribute may refer to an
+@code{NSString} reference for compatibility with the @code{format} attribute
+above.
-@subsection RL78 Named Address Spaces
-@cindex @code{__far} RL78 Named Address Spaces
+The target may also allow additional types in @code{format-arg} attributes.
+@xref{Target Format Checks,,Format Checks Specific to Particular
+Target Machines}.
-On the RL78 target, variables qualified with @code{__far} are accessed
-with 32-bit pointers (20-bit addresses) rather than the default 16-bit
-addresses. Non-far variables are assumed to appear in the topmost
-64@tie{}KiB of the address space.
+@cindex @code{gnu_inline} function attribute
+@item gnu_inline
+This attribute should be used with a function that is also declared
+with the @code{inline} keyword. It directs GCC to treat the function
+as if it were defined in gnu90 mode even when compiling in C99 or
+gnu99 mode.
-@subsection x86 Named Address Spaces
-@cindex x86 named address spaces
+If the function is declared @code{extern}, then this definition of the
+function is used only for inlining. In no case is the function
+compiled as a standalone function, not even if you take its address
+explicitly. Such an address becomes an external reference, as if you
+had only declared the function, and had not defined it. This has
+almost the effect of a macro. The way to use this is to put a
+function definition in a header file with this attribute, and put
+another copy of the function, without @code{extern}, in a library
+file. The definition in the header file causes most calls to the
+function to be inlined. If any uses of the function remain, they
+refer to the single copy in the library. Note that the two
+definitions of the functions need not be precisely the same, although
+if they do not have the same effect your program may behave oddly.
-On the x86 target, variables may be declared as being relative
-to the @code{%fs} or @code{%gs} segments.
+In C, if the function is neither @code{extern} nor @code{static}, then
+the function is compiled as a standalone function, as well as being
+inlined where possible.
-@table @code
-@cindex @code{__seg_fs} x86 named address space
-@cindex @code{__seg_gs} x86 named address space
-@item __seg_fs
-@itemx __seg_gs
-The object is accessed with the respective segment override prefix.
+This is how GCC traditionally handled functions declared
+@code{inline}. Since ISO C99 specifies a different semantics for
+@code{inline}, this function attribute is provided as a transition
+measure and as a useful feature in its own right. This attribute is
+available in GCC 4.1.3 and later. It is available if either of the
+preprocessor macros @code{__GNUC_GNU_INLINE__} or
+@code{__GNUC_STDC_INLINE__} are defined. @xref{Inline,,An Inline
+Function is As Fast As a Macro}.
-The respective segment base must be set via some method specific to
-the operating system. Rather than require an expensive system call
-to retrieve the segment base, these address spaces are not considered
-to be subspaces of the generic (flat) address space. This means that
-explicit casts are required to convert pointers between these address
-spaces and the generic address space. In practice the application
-should cast to @code{uintptr_t} and apply the segment base offset
-that it installed previously.
+In C++, this attribute does not depend on @code{extern} in any way,
+but it still requires the @code{inline} keyword to enable its special
+behavior.
-The preprocessor symbols @code{__SEG_FS} and @code{__SEG_GS} are
-defined when these address spaces are supported.
-@end table
+@cindex @code{hot} function attribute
+@item hot
+The @code{hot} attribute on a function is used to inform the compiler that
+the function is a hot spot of the compiled program. The function is
+optimized more aggressively and on many targets it is placed into a special
+subsection of the text section so all hot functions appear close together,
+improving locality. In C++, the @code{hot} attribute can be applied to types
+with the effect of being propagated to member functions. See
+@ref{C++ Attributes}.
-@node Variadic Macros
-@section Macros with a Variable Number of Arguments.
-@cindex variable number of arguments
-@cindex macro with variable arguments
-@cindex rest argument (in macro)
-@cindex variadic macros
+When profile feedback is available, via @option{-fprofile-use}, hot functions
+are automatically detected and this attribute is ignored.
-In the ISO C standard of 1999, a macro can be declared to accept a
-variable number of arguments much as a function can. The syntax for
-defining the macro is similar to that of a function. Here is an
-example:
+@cindex @code{ifunc} function attribute
+@cindex indirect functions
+@cindex functions that are dynamically resolved
+@item ifunc ("@var{resolver}")
+The @code{ifunc} attribute is used to mark a function as an indirect
+function using the STT_GNU_IFUNC symbol type extension to the ELF
+standard. This allows the resolution of the symbol value to be
+determined dynamically at load time, and an optimized version of the
+routine to be selected for the particular processor or other system
+characteristics determined then. To use this attribute, first define
+the implementation functions available, and a resolver function that
+returns a pointer to the selected implementation function. The
+implementation functions' declarations must match the API of the
+function being implemented. The resolver should be declared to
+be a function taking no arguments and returning a pointer to
+a function of the same type as the implementation. For example:
@smallexample
-#define debug(format, ...) fprintf (stderr, format, __VA_ARGS__)
+void *my_memcpy (void *dst, const void *src, size_t len)
+@{
+ @dots{}
+ return dst;
+@}
+
+static void * (*resolve_memcpy (void))(void *, const void *, size_t)
+@{
+ return my_memcpy; // we will just always select this routine
+@}
@end smallexample
@noindent
-Here @samp{@dots{}} is a @dfn{variable argument}. In the invocation of
-such a macro, it represents the zero or more tokens until the closing
-parenthesis that ends the invocation, including any commas. This set of
-tokens replaces the identifier @code{__VA_ARGS__} in the macro body
-wherever it appears. See the CPP manual for more information.
-
-GCC has long supported variadic macros, and used a different syntax that
-allowed you to give a name to the variable arguments just like any other
-argument. Here is an example:
+The exported header file declaring the function the user calls would
+contain:
@smallexample
-#define debug(format, args...) fprintf (stderr, format, args)
+extern void *memcpy (void *, const void *, size_t);
@end smallexample
@noindent
-This is in all ways equivalent to the ISO C example above, but arguably
-more readable and descriptive.
-
-GNU CPP has two further variadic macro extensions, and permits them to
-be used with either of the above forms of macro definition.
-
-In standard C, you are not allowed to leave the variable argument out
-entirely; but you are allowed to pass an empty argument. For example,
-this invocation is invalid in ISO C, because there is no comma after
-the string:
+allowing the user to call @code{memcpy} as a regular function, unaware of
+the actual implementation. Finally, the indirect function needs to be
+defined in the same translation unit as the resolver function:
@smallexample
-debug ("A message")
+void *memcpy (void *, const void *, size_t)
+ __attribute__ ((ifunc ("resolve_memcpy")));
@end smallexample
-GNU CPP permits you to completely omit the variable arguments in this
-way. In the above examples, the compiler would complain, though since
-the expansion of the macro still has the extra comma after the format
-string.
-
-To help solve this problem, CPP behaves specially for variable arguments
-used with the token paste operator, @samp{##}. If instead you write
+In C++, the @code{ifunc} attribute takes a string that is the mangled name
+of the resolver function. A C++ resolver for a non-static member function
+of class @code{C} should be declared to return a pointer to a non-member
+function taking pointer to @code{C} as the first argument, followed by
+the same arguments as of the implementation function. G++ checks
+the signatures of the two functions and issues
+a @option{-Wattribute-alias} warning for mismatches. To suppress a warning
+for the necessary cast from a pointer to the implementation member function
+to the type of the corresponding non-member function use
+the @option{-Wno-pmf-conversions} option. For example:
@smallexample
-#define debug(format, ...) fprintf (stderr, format, ## __VA_ARGS__)
-@end smallexample
+class S
+@{
+private:
+ int debug_impl (int);
+ int optimized_impl (int);
-@noindent
-and if the variable arguments are omitted or empty, the @samp{##}
-operator causes the preprocessor to remove the comma before it. If you
-do provide some variable arguments in your macro invocation, GNU CPP
-does not complain about the paste operation and instead places the
-variable arguments after the comma. Just like any other pasted macro
-argument, these arguments are not macro expanded.
+ typedef int Func (S*, int);
-@node Escaped Newlines
-@section Slightly Looser Rules for Escaped Newlines
-@cindex escaped newlines
-@cindex newlines (escaped)
+ static Func* resolver ();
+public:
-The preprocessor treatment of escaped newlines is more relaxed
-than that specified by the C90 standard, which requires the newline
-to immediately follow a backslash.
-GCC's implementation allows whitespace in the form
-of spaces, horizontal and vertical tabs, and form feeds between the
-backslash and the subsequent newline. The preprocessor issues a
-warning, but treats it as a valid escaped newline and combines the two
-lines to form a single logical line. This works within comments and
-tokens, as well as between tokens. Comments are @emph{not} treated as
-whitespace for the purposes of this relaxation, since they have not
-yet been replaced with spaces.
+ int interface (int);
+@};
-@node Pointer Arith
-@section Arithmetic on @code{void}- and Function-Pointers
-@cindex void pointers, arithmetic
-@cindex void, size of pointer to
-@cindex function pointers, arithmetic
-@cindex function, size of pointer to
+int S::debug_impl (int) @{ /* @r{@dots{}} */ @}
+int S::optimized_impl (int) @{ /* @r{@dots{}} */ @}
-In GNU C, addition and subtraction operations are supported on pointers to
-@code{void} and on pointers to functions. This is done by treating the
-size of a @code{void} or of a function as 1.
+S::Func* S::resolver ()
+@{
+ int (S::*pimpl) (int)
+ = getenv ("DEBUG") ? &S::debug_impl : &S::optimized_impl;
-A consequence of this is that @code{sizeof} is also allowed on @code{void}
-and on function types, and returns 1.
+ // Cast triggers -Wno-pmf-conversions.
+ return reinterpret_cast<Func*>(pimpl);
+@}
-@opindex Wpointer-arith
-The option @option{-Wpointer-arith} requests a warning if these extensions
-are used.
+int S::interface (int) __attribute__ ((ifunc ("_ZN1S8resolverEv")));
+@end smallexample
-@node Variadic Pointer Args
-@section Pointer Arguments in Variadic Functions
-@cindex pointer arguments in variadic functions
-@cindex variadic functions, pointer arguments
+Indirect functions cannot be weak. Binutils version 2.20.1 or higher
+and GNU C Library version 2.11.1 are required to use this feature.
-Standard C requires that pointer types used with @code{va_arg} in
-functions with variable argument lists either must be compatible with
-that of the actual argument, or that one type must be a pointer to
-@code{void} and the other a pointer to a character type. GNU C
-implements the POSIX XSI extension that additionally permits the use
-of @code{va_arg} with a pointer type to receive arguments of any other
-pointer type.
+@cindex @code{interrupt_handler} function attribute
+@cindex @code{interrupt} function attribute
+@item interrupt
+@itemx interrupt_handler
+Many GCC back ends support attributes to indicate that a function is
+an interrupt handler, which tells the compiler to generate function
+entry and exit sequences that differ from those from regular
+functions. The exact syntax and behavior are target-specific;
+refer to the following subsections for details.
-In particular, in GNU C @samp{va_arg (ap, void *)} can safely be used
-to consume an argument of any pointer type.
+@cindex @code{leaf} function attribute
+@item leaf
+Calls to external functions with this attribute must return to the
+current compilation unit only by return or by exception handling. In
+particular, a leaf function is not allowed to invoke callback functions
+passed to it from the current compilation unit, directly call functions
+exported by the unit, or @code{longjmp} into the unit. Leaf functions
+might still call functions from other compilation units and thus they
+are not necessarily leaf in the sense that they contain no function
+calls at all.
-@node Pointers to Arrays
-@section Pointers to Arrays with Qualifiers Work as Expected
-@cindex pointers to arrays
-@cindex const qualifier
+The attribute is intended for library functions to improve dataflow
+analysis. The compiler takes the hint that any data not escaping the
+current compilation unit cannot be used or modified by the leaf
+function. For example, the @code{sin} function is a leaf function, but
+@code{qsort} is not.
-In GNU C, pointers to arrays with qualifiers work similar to pointers
-to other qualified types. For example, a value of type @code{int (*)[5]}
-can be used to initialize a variable of type @code{const int (*)[5]}.
-These types are incompatible in ISO C because the @code{const} qualifier
-is formally attached to the element type of the array and not the
-array itself.
+Note that leaf functions might indirectly run a signal handler defined
+in the current compilation unit that uses static variables. Similarly,
+when lazy symbol resolution is in effect, leaf functions might invoke
+indirect functions whose resolver function or implementation function is
+defined in the current compilation unit and uses static variables. There
+is no standard-compliant way to write such a signal handler, resolver
+function, or implementation function, and the best that you can do is to
+remove the @code{leaf} attribute or mark all such static variables
+@code{volatile}. Lastly, for ELF-based systems that support symbol
+interposition, care should be taken that functions defined in the
+current compilation unit do not unexpectedly interpose other symbols
+based on the defined standards mode and defined feature test macros;
+otherwise an inadvertent callback would be added.
-@smallexample
-extern void
-transpose (int N, int M, double out[M][N], const double in[N][M]);
-double x[3][2];
-double y[2][3];
-@r{@dots{}}
-transpose(3, 2, y, x);
-@end smallexample
+The attribute has no effect on functions defined within the current
+compilation unit. This is to allow easy merging of multiple compilation
+units into one, for example, by using the link-time optimization. For
+this reason the attribute is not allowed on types to annotate indirect
+calls.
-@node Case Ranges
-@section Case Ranges
-@cindex case ranges
-@cindex ranges in case statements
+@cindex @code{malloc} function attribute
+@cindex functions that behave like malloc
+@item malloc
+@item malloc (@var{deallocator})
+@item malloc (@var{deallocator}, @var{ptr-index})
+Attribute @code{malloc} indicates that a function is @code{malloc}-like,
+i.e., that the pointer @var{P} returned by the function cannot alias any
+other pointer valid when the function returns, and moreover no
+pointers to valid objects occur in any storage addressed by @var{P}. In
+addition, GCC predicts that a function with the attribute returns
+non-null in most cases.
-You can specify a range of consecutive values in a single @code{case} label,
-like this:
+Independently, the form of the attribute with one or two arguments
+associates @code{deallocator} as a suitable deallocation function for
+pointers returned from the @code{malloc}-like function. @var{ptr-index}
+denotes the positional argument to which when the pointer is passed in
+calls to @code{deallocator} has the effect of deallocating it.
-@smallexample
-case @var{low} ... @var{high}:
-@end smallexample
+Using the attribute with no arguments is designed to improve optimization
+by relying on the aliasing property it implies. Functions like @code{malloc}
+and @code{calloc} have this property because they return a pointer to
+uninitialized or zeroed-out, newly obtained storage. However, functions
+like @code{realloc} do not have this property, as they may return pointers
+to storage containing pointers to existing objects. Additionally, since
+all such functions are assumed to return null only infrequently, callers
+can be optimized based on that assumption.
-@noindent
-This has the same effect as the proper number of individual @code{case}
-labels, one for each integer value from @var{low} to @var{high}, inclusive.
+Associating a function with a @var{deallocator} helps detect calls to
+mismatched allocation and deallocation functions and diagnose them under
+the control of options such as @option{-Wmismatched-dealloc}. It also
+makes it possible to diagnose attempts to deallocate objects that were not
+allocated dynamically, by @option{-Wfree-nonheap-object}. To indicate
+that an allocation function both satisfies the nonaliasing property and
+has a deallocator associated with it, both the plain form of the attribute
+and the one with the @var{deallocator} argument must be used. The same
+function can be both an allocator and a deallocator. Since inlining one
+of the associated functions but not the other could result in apparent
+mismatches, this form of attribute @code{malloc} is not accepted on inline
+functions. For the same reason, using the attribute prevents both
+the allocation and deallocation functions from being expanded inline.
-This feature is especially useful for ranges of ASCII character codes:
+For example, besides stating that the functions return pointers that do
+not alias any others, the following declarations make @code{fclose}
+a suitable deallocator for pointers returned from all functions except
+@code{popen}, and @code{pclose} as the only suitable deallocator for
+pointers returned from @code{popen}. The deallocator functions must
+be declared before they can be referenced in the attribute.
@smallexample
-case 'A' ... 'Z':
-@end smallexample
-
-@strong{Be careful:} Write spaces around the @code{...}, for otherwise
-it may be parsed wrong when you use it with integer values. For example,
-write this:
+int fclose (FILE*);
+int pclose (FILE*);
-@smallexample
-case 1 ... 5:
+__attribute__ ((malloc, malloc (fclose, 1)))
+ FILE* fdopen (int, const char*);
+__attribute__ ((malloc, malloc (fclose, 1)))
+ FILE* fopen (const char*, const char*);
+__attribute__ ((malloc, malloc (fclose, 1)))
+ FILE* fmemopen(void *, size_t, const char *);
+__attribute__ ((malloc, malloc (pclose, 1)))
+ FILE* popen (const char*, const char*);
+__attribute__ ((malloc, malloc (fclose, 1)))
+ FILE* tmpfile (void);
@end smallexample
-@noindent
-rather than this:
+The warnings guarded by @option{-fanalyzer} respect allocation and
+deallocation pairs marked with the @code{malloc}. In particular:
-@smallexample
-case 1...5:
-@end smallexample
+@itemize @bullet
-@node Mixed Labels and Declarations
-@section Mixed Declarations, Labels and Code
-@cindex mixed declarations and code
-@cindex declarations, mixed with code
-@cindex code, mixed with declarations
+@item
+The analyzer emits a @option{-Wanalyzer-mismatching-deallocation}
+diagnostic if there is an execution path in which the result of an
+allocation call is passed to a different deallocator.
-ISO C99 and ISO C++ allow declarations and code to be freely mixed
-within compound statements. ISO C23 allows labels to be
-placed before declarations and at the end of a compound statement.
-As an extension, GNU C also allows all this in C90 mode. For example,
-you could do:
+@item
+The analyzer emits a @option{-Wanalyzer-double-free}
+diagnostic if there is an execution path in which a value is passed
+more than once to a deallocation call.
+@item
+The analyzer considers the possibility that an allocation function
+could fail and return null. If there are
+execution paths in which an unchecked result of an allocation call is
+dereferenced or passed to a function requiring a non-null argument,
+it emits
+@option{-Wanalyzer-possible-null-dereference} and
+@option{-Wanalyzer-possible-null-argument} diagnostics.
+If the allocator always returns non-null, use
+@code{__attribute__ ((returns_nonnull))} to suppress these warnings.
+For example:
@smallexample
-int i;
-/* @r{@dots{}} */
-i++;
-int j = i + 2;
+char *xstrdup (const char *)
+ __attribute__((malloc (free), returns_nonnull));
@end smallexample
-Each identifier is visible from where it is declared until the end of
-the enclosing block.
+@item
+The analyzer emits a @option{-Wanalyzer-use-after-free}
+diagnostic if there is an execution path in which the memory passed
+by pointer to a deallocation call is used after the deallocation.
-@node Function Attributes
-@section Declaring Attributes of Functions
-@cindex function attributes
-@cindex declaring attributes of functions
+@item
+The analyzer emits a @option{-Wanalyzer-malloc-leak} diagnostic if
+there is an execution path in which the result of an allocation call
+is leaked (without being passed to the deallocation function).
-In GNU C and C++, you can use function attributes to specify certain
-function properties that may help the compiler optimize calls or
-check code more carefully for correctness. For example, you
-can use attributes to specify that a function never returns
-(@code{noreturn}), returns a value depending only on the values of
-its arguments (@code{const}), or has @code{printf}-style arguments
-(@code{format}).
+@item
+The analyzer emits a @option{-Wanalyzer-free-of-non-heap} diagnostic
+if a deallocation function is used on a global or on-stack variable.
-You can also use attributes to control memory placement, code
-generation options or call/return conventions within the function
-being annotated. Many of these attributes are target-specific. For
-example, many targets support attributes for defining interrupt
-handler functions, which typically must follow special register usage
-and return conventions. Such attributes are described in the subsection
-for each target. However, a considerable number of attributes are
-supported by most, if not all targets. Those are described in
-the @ref{Common Function Attributes} 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::} prefix on attribute names. Note that the exact rules for
-placement of attributes in your source code are different depending on
-which syntax you use. @xref{Attribute Syntax}, for details.
-
-Compatible attribute specifications on distinct declarations
-of the same function are merged. An attribute specification that is not
-compatible with attributes already applied to a declaration of the same
-function is ignored with a warning.
+@end itemize
-Some function attributes take one or more arguments that refer to
-the function's parameters by their positions within the function parameter
-list. Such attribute arguments are referred to as @dfn{positional arguments}.
-Unless specified otherwise, positional arguments that specify properties
-of parameters with pointer types can also specify the same properties of
-the implicit C++ @code{this} argument in non-static member functions, and
-of parameters of reference to a pointer type. For ordinary functions,
-position one refers to the first parameter on the list. In C++ non-static
-member functions, position one refers to the implicit @code{this} pointer.
-The same restrictions and effects apply to function attributes used with
-ordinary functions or C++ member functions.
+The analyzer assumes that deallocators can gracefully handle the null
+pointer. If this is not the case, the deallocator can be marked with
+@code{__attribute__((nonnull))} so that @option{-fanalyzer} can emit
+a @option{-Wanalyzer-possible-null-argument} diagnostic for code paths
+in which the deallocator is called with null.
-GCC also supports attributes on
-variable declarations (@pxref{Variable Attributes}),
-labels (@pxref{Label Attributes}),
-enumerators (@pxref{Enumerator Attributes}),
-statements (@pxref{Statement Attributes}),
-types (@pxref{Type Attributes}),
-and on field declarations (for @code{tainted_args}).
+@cindex @code{no_icf} function attribute
+@item no_icf
+This function attribute prevents a functions from being merged with another
+semantically equivalent function.
-There is some overlap between the purposes of attributes and pragmas
-(@pxref{Pragmas,,Pragmas Accepted by GCC}). It has been
-found convenient to use @code{__attribute__} to achieve a natural
-attachment of attributes to their corresponding declarations, whereas
-@code{#pragma} is of use for compatibility with other compilers
-or constructs that do not naturally form part of the grammar.
+@cindex @code{no_instrument_function} function attribute
+@opindex finstrument-functions
+@opindex p
+@opindex pg
+@item no_instrument_function
+If any of @option{-finstrument-functions}, @option{-p}, or @option{-pg} are
+given, profiling function calls are
+generated at entry and exit of most user-compiled functions.
+Functions with this attribute are not so instrumented.
-In addition to the attributes documented here,
-GCC plugins may provide their own attributes.
+@cindex @code{no_profile_instrument_function} function attribute
+@item no_profile_instrument_function
+The @code{no_profile_instrument_function} attribute on functions is used
+to inform the compiler that it should not process any profile feedback based
+optimization code instrumentation.
-@menu
-* Common Function Attributes::
-* AArch64 Function Attributes::
-* AMD GCN Function Attributes::
-* ARC Function Attributes::
-* ARM Function Attributes::
-* AVR Function Attributes::
-* Blackfin Function Attributes::
-* BPF Function Attributes::
-* C-SKY Function Attributes::
-* Epiphany Function Attributes::
-* H8/300 Function Attributes::
-* IA-64 Function Attributes::
-* LoongArch Function Attributes::
-* M32C Function Attributes::
-* M32R/D Function Attributes::
-* m68k Function Attributes::
-* MCORE Function Attributes::
-* MicroBlaze Function Attributes::
-* Microsoft Windows Function Attributes::
-* MIPS Function Attributes::
-* MSP430 Function Attributes::
-* NDS32 Function Attributes::
-* Nvidia PTX Function Attributes::
-* PowerPC Function Attributes::
-* RISC-V Function Attributes::
-* RL78 Function Attributes::
-* RX Function Attributes::
-* S/390 Function Attributes::
-* SH Function Attributes::
-* Symbian OS Function Attributes::
-* V850 Function Attributes::
-* Visium Function Attributes::
-* x86 Function Attributes::
-* Xstormy16 Function Attributes::
-@end menu
+@cindex @code{no_reorder} function attribute
+@item no_reorder
+Do not reorder functions or variables marked @code{no_reorder}
+against each other or top level assembler statements the executable.
+The actual order in the program will depend on the linker command
+line. Static variables marked like this are also not removed.
+This has a similar effect
+as the @option{-fno-toplevel-reorder} option, but only applies to the
+marked symbols.
-@node Common Function Attributes
-@subsection Common Function Attributes
+@cindex @code{no_sanitize} function attribute
+@item no_sanitize ("@var{sanitize_option}")
+The @code{no_sanitize} attribute on functions is used
+to inform the compiler that it should not do sanitization of any option
+mentioned in @var{sanitize_option}. A list of values acceptable by
+the @option{-fsanitize} option can be provided.
-The following attributes are supported on most targets.
+@smallexample
+void __attribute__ ((no_sanitize ("alignment", "object-size")))
+f () @{ /* @r{Do something.} */; @}
+void __attribute__ ((no_sanitize ("alignment,object-size")))
+g () @{ /* @r{Do something.} */; @}
+@end smallexample
-@table @code
-@c Keep this table alphabetized by attribute name. Treat _ as space.
+@cindex @code{no_sanitize_address} function attribute
+@item no_sanitize_address
+@itemx no_address_safety_analysis
+The @code{no_sanitize_address} attribute on functions is used
+to inform the compiler that it should not instrument memory accesses
+in the function when compiling with the @option{-fsanitize=address} option.
+The @code{no_address_safety_analysis} is a deprecated alias of the
+@code{no_sanitize_address} attribute, new code should use
+@code{no_sanitize_address}.
-@cindex @code{access} function attribute
-@item access (@var{access-mode}, @var{ref-index})
-@itemx access (@var{access-mode}, @var{ref-index}, @var{size-index})
+@cindex @code{no_sanitize_thread} function attribute
+@item no_sanitize_thread
+The @code{no_sanitize_thread} attribute on functions is used
+to inform the compiler that it should not instrument memory accesses
+in the function when compiling with the @option{-fsanitize=thread} option.
-The @code{access} attribute enables the detection of invalid or unsafe
-accesses by functions to which they apply or their callers, as well as
-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.
+@cindex @code{no_sanitize_undefined} function attribute
+@item no_sanitize_undefined
+The @code{no_sanitize_undefined} attribute on functions is used
+to inform the compiler that it should not check for undefined behavior
+in the function when compiling with the @option{-fsanitize=undefined} option.
-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.
+@cindex @code{no_sanitize_coverage} function attribute
+@item no_sanitize_coverage
+The @code{no_sanitize_coverage} attribute on functions is used
+to inform the compiler that it should not do coverage-guided
+fuzzing code instrumentation (@option{-fsanitize-coverage}).
-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.
+@cindex @code{no_split_stack} function attribute
+@opindex fsplit-stack
+@item no_split_stack
+If @option{-fsplit-stack} is given, functions have a small
+prologue which decides whether to split the stack. Functions with the
+@code{no_split_stack} attribute do not have that prologue, and thus
+may run with only a small amount of stack space available.
-The optional @var{size-index} positional argument denotes 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
-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.
+@cindex @code{no_stack_limit} function attribute
+@item no_stack_limit
+This attribute locally overrides the @option{-fstack-limit-register}
+and @option{-fstack-limit-symbol} command-line options; it has the effect
+of disabling stack limit checking in the function it applies to.
-The @code{read_only} access mode specifies that the pointer to which it
-applies is used to read the referenced object but not write to it. Unless
-the argument specifying the size of the access denoted by @var{size-index}
-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{memcpy} function.
+@cindex @code{no_stack_protector} function attribute
+@item no_stack_protector
+This attribute prevents stack protection code for the function.
-@smallexample
-__attribute__ ((access (read_only, 1)))
-int puts (const char*);
+@cindex @code{noclone} function attribute
+@item noclone
+This function attribute prevents a function from being considered for
+cloning---a mechanism that produces specialized copies of functions
+and which is (currently) performed by interprocedural constant
+propagation.
-__attribute__ ((access (read_only, 2, 3)))
-void* memcpy (void*, const void*, size_t);
-@end smallexample
+@cindex @code{noinline} function attribute
+@item noinline
+This function attribute prevents a function from being considered for
+inlining. It also disables some other interprocedural optimizations; it's
+preferable to use the more comprehensive @code{noipa} attribute instead
+if that is your goal.
-The @code{read_write} access mode applies to arguments of pointer types
-without the @code{const} qualifier. It specifies that the pointer to which
-it applies is used to both read and write the referenced object. Unless
-the argument specifying the size of the access denoted by @var{size-index}
-is zero, the object referenced by the pointer must be initialized. An example
-of the use of the @code{read_write} access mode is the first argument to
-the @code{strcat} function.
+@c Don't enumerate the optimizations by name here; we try to be
+@c future-compatible with this mechanism.
+Even if a function is declared with the @code{noinline} attribute,
+there are optimizations other than inlining that can cause calls to be
+optimized away if it does not have side effects, although the function
+call is live. To keep such calls from being optimized away, put
@smallexample
-__attribute__ ((access (read_write, 1), access (read_only, 2)))
-char* strcat (char*, const char*);
+asm ("");
@end smallexample
-The @code{write_only} access mode applies to arguments of pointer types
-without the @code{const} qualifier. It specifies that the pointer to which
-it applies is used to write to the referenced object but not read from it.
-The object referenced by the pointer need not be initialized. An example
-of the use of the @code{write_only} access mode is the first argument to
-the @code{strcpy} function, or the first two arguments to the @code{fgets}
-function.
-
-@smallexample
-__attribute__ ((access (write_only, 1), access (read_only, 2)))
-char* strcpy (char*, const char*);
-
-__attribute__ ((access (write_only, 1, 2), access (read_write, 3)))
-int fgets (char*, int, FILE*);
-@end smallexample
+@noindent
+(@pxref{Extended Asm}) in the called function, to serve as a special
+side effect.
-The access mode @code{none} specifies that the pointer 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
-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.
-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}.
-
-Note that the @code{access} attribute merely specifies how an object
-referenced by the pointer argument can be accessed; it does not imply that
-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
-caveats.
+@cindex @code{noipa} function attribute
+@item noipa
+Disable interprocedural optimizations between the function with this
+attribute and its callers, as if the body of the function is not available
+when optimizing callers and the callers are unavailable when optimizing
+the body. This attribute implies @code{noinline}, @code{noclone} and
+@code{no_icf} attributes. However, this attribute is not equivalent
+to a combination of other attributes, because its purpose is to suppress
+existing and future optimizations employing interprocedural analysis,
+including those that do not have an attribute suitable for disabling
+them individually.
-@cindex @code{alias} function attribute
-@item alias ("@var{target}")
-The @code{alias} attribute causes the declaration to be emitted as an alias
-for another symbol, which must have been previously declared with the same
-type, and for variables, also the same size and alignment. Declaring an alias
-with a different type than the target is undefined and may be diagnosed. As
-an example, the following declarations:
+@cindex @code{nonnull} function attribute
+@cindex functions with non-null pointer arguments
+@item nonnull
+@itemx nonnull (@var{arg-index}, @dots{})
+The @code{nonnull} attribute may be applied to a function that takes at
+least one argument of a pointer type. It indicates that the referenced
+arguments must be non-null pointers. For instance, the declaration:
@smallexample
-void __f () @{ /* @r{Do something.} */; @}
-void f () __attribute__ ((weak, alias ("__f")));
+extern void *
+my_memcpy (void *dest, const void *src, size_t len)
+ __attribute__((nonnull (1, 2)));
@end smallexample
@noindent
-define @samp{f} to be a weak alias for @samp{__f}. In C++, the mangled name
-for the target must be used. It is an error if @samp{__f} is not defined in
-the same translation unit.
-
-This attribute requires assembler and object file support,
-and may not be available on all targets.
-
-@cindex @code{aligned} function attribute
-@item aligned
-@itemx aligned (@var{alignment})
-The @code{aligned} attribute specifies a minimum alignment for
-the first instruction of the function, measured in bytes. When specified,
-@var{alignment} must be an integer constant power of 2. Specifying no
-@var{alignment} argument implies the ideal alignment for the target.
-The @code{__alignof__} operator can be used to determine what that is
-(@pxref{Alignment}). The attribute has no effect when a definition for
-the function is not provided in the same translation unit.
-
-The attribute cannot be used to decrease the alignment of a function
-previously declared with a more restrictive alignment; only to increase
-it. Attempts to do otherwise are diagnosed. Some targets specify
-a minimum default alignment for functions that is greater than 1. On
-such targets, specifying a less restrictive alignment is silently ignored.
-Using the attribute overrides the effect of the @option{-falign-functions}
-(@pxref{Optimize Options}) option for this function.
-
-Note that the effectiveness of @code{aligned} attributes may be
-limited by inherent limitations in the system linker
-and/or object file format. On some systems, the
-linker is only able to arrange for functions to be aligned up to a
-certain maximum alignment. (For some linkers, the maximum supported
-alignment may be very very small.) See your linker documentation for
-further information.
+informs the compiler that, in calls to @code{my_memcpy}, arguments
+@var{dest} and @var{src} must be non-null.
-The @code{aligned} attribute can also be used for variables and fields
-(@pxref{Variable Attributes}.)
+The attribute has an effect both on functions calls and function definitions.
-@cindex @code{alloc_align} function attribute
-@item alloc_align (@var{position})
-The @code{alloc_align} attribute may be applied to a function that
-returns a pointer and takes at least one argument of an integer or
-enumerated type.
-It indicates that the returned pointer is aligned on a boundary given
-by the function argument at @var{position}. Meaningful alignments are
-powers of 2 greater than one. GCC uses this information to improve
-pointer alignment analysis.
+For function calls:
+@itemize @bullet
+@item If the compiler determines that a null pointer is
+passed in an argument slot marked as non-null, and the
+@option{-Wnonnull} option is enabled, a warning is issued.
+@xref{Warning Options}.
+@item The @option{-fisolate-erroneous-paths-attribute} option can be
+specified to have GCC transform calls with null arguments to non-null
+functions into traps. @xref{Optimize Options}.
+@item The compiler may also perform optimizations based on the
+knowledge that certain function arguments cannot be null. These
+optimizations can be disabled by the
+@option{-fno-delete-null-pointer-checks} option. @xref{Optimize Options}.
+@end itemize
-The function parameter denoting the allocated alignment is specified by
-one constant integer argument whose number is the argument of the attribute.
-Argument numbering starts at one.
+For function definitions:
+@itemize @bullet
+@item If the compiler determines that a function parameter that is
+marked with nonnull is compared with null, and
+@option{-Wnonnull-compare} option is enabled, a warning is issued.
+@xref{Warning Options}.
+@item The compiler may also perform optimizations based on the
+knowledge that @code{nonnull} parameters cannot be null. This can
+currently not be disabled other than by removing the nonnull
+attribute.
+@end itemize
-For instance,
+If no @var{arg-index} is given to the @code{nonnull} attribute,
+all pointer arguments are marked as non-null. To illustrate, the
+following declaration is equivalent to the previous example:
@smallexample
-void* my_memalign (size_t, size_t) __attribute__ ((alloc_align (1)));
+extern void *
+my_memcpy (void *dest, const void *src, size_t len)
+ __attribute__((nonnull));
@end smallexample
-@noindent
-declares that @code{my_memalign} returns memory with minimum alignment
-given by parameter 1.
+@cindex @code{nonnull_if_nonzero} function attribute
+@item nonnull_if_nonzero
+@itemx nonnull_if_nonzero (@var{arg-index}, @var{arg2-index})
+The @code{nonnull_if_nonzero} attribute is a conditional version of the
+@code{nonnull} attribute. It has two 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.
-@cindex @code{alloc_size} function attribute
-@item alloc_size (@var{position})
-@itemx alloc_size (@var{position-1}, @var{position-2})
-The @code{alloc_size} attribute may be applied to a function that
-returns a pointer and takes at least one argument of an integer or
-enumerated type.
-It indicates that the returned pointer points to memory whose size is
-given by the function argument at @var{position-1}, or by the product
-of the arguments at @var{position-1} and @var{position-2}. Meaningful
-sizes are positive values less than @code{PTRDIFF_MAX}. GCC uses this
-information to improve the results of @code{__builtin_object_size}.
+@smallexample
+extern void *
+my_memcpy (void *dest, const void *src, size_t len)
+ __attribute__((nonnull (1, 2)));
+extern void *
+my_memcpy2 (void *dest, const void *src, size_t len)
+ __attribute__((nonnull_if_nonzero (1, 3),
+ nonnull_if_nonzero (2, 3)));
+@end smallexample
-The function parameter(s) denoting the allocated size are specified by
-one or two integer arguments supplied to the attribute. The allocated size
-is either the value of the single function argument specified or the product
-of the two function arguments specified. Argument numbering starts at
-one for ordinary functions, and at two for C++ non-static member functions.
+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
+used on declarations which have e.g.@: an exception for zero sizes,
+in which case null may be passed.
-For instance,
+@cindex @code{noplt} function attribute
+@item noplt
+The @code{noplt} attribute is the counterpart to option @option{-fno-plt}.
+Calls to functions marked with this attribute in position-independent code
+do not use the PLT.
@smallexample
-void* my_calloc (size_t, size_t) __attribute__ ((alloc_size (1, 2)));
-void* my_realloc (void*, size_t) __attribute__ ((alloc_size (2)));
-@end smallexample
-
-@noindent
-declares that @code{my_calloc} returns memory of the size given by
-the product of parameter 1 and 2 and that @code{my_realloc} returns memory
-of the size given by parameter 2.
+@group
+/* Externally defined function foo. */
+int foo () __attribute__ ((noplt));
-@cindex @code{always_inline} function attribute
-@item always_inline
-Generally, functions are not inlined unless optimization is specified.
-For functions declared inline, this attribute inlines the function
-independent of any restrictions that otherwise apply to inlining.
-Failure to inline such a function is diagnosed as an error.
-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.
+int
+main (/* @r{@dots{}} */)
+@{
+ /* @r{@dots{}} */
+ foo ();
+ /* @r{@dots{}} */
+@}
+@end group
+@end smallexample
-@cindex @code{artificial} function attribute
-@item artificial
-This attribute is useful for small inline wrappers that if possible
-should appear during debugging as a unit. Depending on the debug
-info format it either means marking the function as artificial
-or using the caller location for all instructions within the inlined
-body.
+The @code{noplt} attribute on function @code{foo}
+tells the compiler to assume that
+the function @code{foo} is externally defined and that the call to
+@code{foo} must avoid the PLT
+in position-independent code.
-@cindex @code{assume_aligned} function attribute
-@item assume_aligned (@var{alignment})
-@itemx assume_aligned (@var{alignment}, @var{offset})
-The @code{assume_aligned} attribute may be applied to a function that
-returns a pointer. It indicates that the returned pointer is aligned
-on a boundary given by @var{alignment}. If the attribute has two
-arguments, the second argument is misalignment @var{offset}. Meaningful
-values of @var{alignment} are powers of 2 greater than one. Meaningful
-values of @var{offset} are greater than zero and less than @var{alignment}.
+In position-dependent code, a few targets also convert calls to
+functions that are marked to not use the PLT to use the GOT instead.
-For instance
+@cindex @code{noreturn} function attribute
+@cindex functions that never return
+@item noreturn
+A few standard library functions, such as @code{abort} and @code{exit},
+cannot return. GCC knows this automatically. Some programs define
+their own functions that never return. You can declare them
+@code{noreturn} to tell the compiler this fact. For example,
@smallexample
-void* my_alloc1 (size_t) __attribute__((assume_aligned (16)));
-void* my_alloc2 (size_t) __attribute__((assume_aligned (32, 8)));
+@group
+void fatal () __attribute__ ((noreturn));
+
+void
+fatal (/* @r{@dots{}} */)
+@{
+ /* @r{@dots{}} */ /* @r{Print error message.} */ /* @r{@dots{}} */
+ exit (1);
+@}
+@end group
@end smallexample
-@noindent
-declares that @code{my_alloc1} returns 16-byte aligned pointers and
-that @code{my_alloc2} returns a pointer whose value modulo 32 is equal
-to 8.
-
-@cindex @code{cold} function attribute
-@item cold
-The @code{cold} attribute on functions is used to inform the compiler that
-the function is unlikely to be executed. The function is optimized for
-size rather than speed and on many targets it is placed into a special
-subsection of the text section so all cold functions appear close together,
-improving code locality of non-cold parts of program. The paths leading
-to calls of cold functions within code are marked as unlikely by the branch
-prediction mechanism. It is thus useful to mark functions used to handle
-unlikely conditions, such as @code{perror}, as cold to improve optimization
-of hot functions that do call marked functions in rare occasions. In C++,
-the @code{cold} attribute can be applied to types with the effect of being
-propagated to member functions. See
-@ref{C++ Attributes}.
-
-When profile feedback is available, via @option{-fprofile-use}, cold functions
-are automatically detected and this attribute is ignored.
+The @code{noreturn} keyword tells the compiler to assume that
+@code{fatal} cannot return. It can then optimize without regard to what
+would happen if @code{fatal} ever did return. This makes slightly
+better code. More importantly, it helps avoid spurious warnings of
+uninitialized variables.
-@cindex @code{const} function attribute
-@cindex functions that have no side effects
-@item const
-Calls to functions whose return value is not affected by changes to
-the observable state of the program and that have no observable effects
-on such state other than to return a value may lend themselves to
-optimizations such as common subexpression elimination. Declaring such
-functions with the @code{const} attribute allows GCC to avoid emitting
-some calls in repeated invocations of the function with the same argument
-values.
+The @code{noreturn} keyword does not affect the exceptional path when that
+applies: a @code{noreturn}-marked function may still return to the caller
+by throwing an exception or calling @code{longjmp}.
-For example,
+In order to preserve backtraces, GCC will never turn calls to
+@code{noreturn} functions into tail calls.
-@smallexample
-int square (int) __attribute__ ((const));
-@end smallexample
+Do not assume that registers saved by the calling function are
+restored before calling the @code{noreturn} function.
-@noindent
-tells GCC that subsequent calls to function @code{square} with the same
-argument value can be replaced by the result of the first call regardless
-of the statements in between.
+It does not make sense for a @code{noreturn} function to have a return
+type other than @code{void}.
-The @code{const} attribute prohibits a function from reading objects
-that affect its return value between successive invocations. However,
-functions declared with the attribute can safely read objects that do
-not change their return value, such as non-volatile constants.
+@cindex @code{nothrow} function attribute
+@item nothrow
+The @code{nothrow} attribute is used to inform the compiler that a
+function cannot throw an exception. For example, most functions in
+the standard C library can be guaranteed not to throw an exception
+with the notable exceptions of @code{qsort} and @code{bsearch} that
+take function pointer arguments.
-The @code{const} attribute imposes greater restrictions on a function's
-definition than the similar @code{pure} attribute. Declaring the same
-function with both the @code{const} and the @code{pure} attribute is
-diagnosed. Because a const function cannot have any observable side
-effects it does not make sense for it to return @code{void}. Declaring
-such a function is diagnosed.
+@cindex @code{null_terminated_string_arg} function attribute
+@item null_terminated_string_arg
+@itemx null_terminated_string_arg (@var{N})
+The @code{null_terminated_string_arg} attribute may be applied to a
+function that takes a @code{char *} or @code{const char *} at
+referenced argument @var{N}.
-@cindex pointer arguments
-Note that a function that has pointer arguments and examines the data
-pointed to must @emph{not} be declared @code{const} if the pointed-to
-data might change between successive invocations of the function. In
-general, since a function cannot distinguish data that might change
-from data that cannot, const functions should never take pointer or,
-in C++, reference arguments. Likewise, a function that calls a non-const
-function usually must not be const itself.
+It indicates that the passed argument must be a C-style null-terminated
+string. Specifically, the presence of the attribute implies that, if
+the pointer is non-null, the function may scan through the referenced
+buffer looking for the first zero byte.
-@cindex @code{constructor} function attribute
-@cindex @code{destructor} function attribute
-@item constructor
-@itemx destructor
-@itemx constructor (@var{priority})
-@itemx destructor (@var{priority})
-The @code{constructor} attribute causes the function to be called
-automatically before execution enters @code{main ()}. Similarly, the
-@code{destructor} attribute causes the function to be called
-automatically after @code{main ()} completes or @code{exit ()} is
-called. Functions with these attributes are useful for
-initializing data that is used implicitly during the execution of
-the program.
+In particular, when the analyzer is enabled (via @option{-fanalyzer}),
+if the pointer is non-null, it will simulate scanning for the first
+zero byte in the referenced buffer, and potentially emit
+@option{-Wanalyzer-use-of-uninitialized-value}
+or @option{-Wanalyzer-out-of-bounds} on improperly terminated buffers.
-On some 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
-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.
+For example, given the following:
-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.
+@smallexample
+char *example_1 (const char *p)
+ __attribute__((null_terminated_string_arg (1)));
+@end smallexample
-@cindex @code{copy} function attribute
-@item copy
-@itemx copy (@var{function})
-The @code{copy} attribute applies the set of attributes with which
-@var{function} has been declared to the declaration of the function
-to which the attribute is applied. The attribute is designed for
-libraries that define aliases or function resolvers that are expected
-to specify the same set of attributes as their targets. The @code{copy}
-attribute can be used with functions, variables, or types. However,
-the kind of symbol to which the attribute is applied (either function
-or variable) must match the kind of symbol to which the argument refers.
-The @code{copy} attribute copies only syntactic and semantic attributes
-but not attributes that affect a symbol's linkage or visibility such as
-@code{alias}, @code{visibility}, or @code{weak}. The @code{deprecated}
-and @code{target_clones} attribute are also not copied.
-@xref{Common Type Attributes}.
-@xref{Common Variable Attributes}.
+the analyzer will check that any non-null pointers passed to the function
+are validly terminated.
-For example, the @var{StrongAlias} macro below makes use of the @code{alias}
-and @code{copy} attributes to define an alias named @var{alloc} for function
-@var{allocate} declared with attributes @var{alloc_size}, @var{malloc}, and
-@var{nothrow}. Thanks to the @code{__typeof__} operator the alias has
-the same type as the target function. As a result of the @code{copy}
-attribute the alias also shares the same attributes as the target.
+If the parameter must be non-null, it is appropriate to use both this
+attribute and the attribute @code{nonnull}, such as in:
@smallexample
-#define StrongAlias(TargetFunc, AliasDecl) \
- extern __typeof__ (TargetFunc) AliasDecl \
- __attribute__ ((alias (#TargetFunc), copy (TargetFunc)));
-
-extern __attribute__ ((alloc_size (1), malloc, nothrow))
- void* allocate (size_t);
-StrongAlias (allocate, alloc);
+extern char *example_2 (const char *p)
+ __attribute__((null_terminated_string_arg (1),
+ nonnull (1)));
@end smallexample
-@cindex @code{deprecated} function attribute
-@item deprecated
-@itemx deprecated (@var{msg})
-The @code{deprecated} attribute results in a warning if the function
-is used anywhere in the source file. This is useful when identifying
-functions that are expected to be removed in a future version of a
-program. The warning also includes the location of the declaration
-of the deprecated function, to enable users to easily find further
-information about why the function is deprecated, or what they should
-do instead. Note that the warnings only occurs for uses:
+See the @code{nonnull} attribute for more information and
+caveats.
+
+If the pointer argument is also referred to by an @code{access} attribute on the
+function with @var{access-mode} either @code{read_only} or @code{read_write}
+and the latter attribute has the optional @var{size-index} argument
+referring to a size argument, this expresses the maximum size of the access.
+For example, given:
@smallexample
-int old_fn () __attribute__ ((deprecated));
-int old_fn ();
-int (*fn_ptr)() = old_fn;
+extern char *example_fn (const char *p, size_t n)
+ __attribute__((null_terminated_string_arg (1),
+ access (read_only, 1, 2),
+ nonnull (1)));
@end smallexample
-@noindent
-results in a warning on line 3 but not line 2. The optional @var{msg}
-argument, which must be a string, is printed in the warning if
-present.
-
-The @code{deprecated} attribute can also be used for variables and
-types (@pxref{Variable Attributes}, @pxref{Type Attributes}.)
+the analyzer will require the first parameter to be non-null, and either
+be validly null-terminated, or validly readable up to the size specified by
+the second parameter.
-The message attached to the attribute is affected by the setting of
-the @option{-fmessage-length} option.
+@cindex @code{optimize} function attribute
+@item optimize (@var{level}, @dots{})
+@item optimize (@var{string}, @dots{})
+The @code{optimize} attribute is used to specify that a function is to
+be compiled with different optimization options than specified on the
+command line. The optimize attribute arguments of a function behave
+as if appended to the command-line.
-@cindex @code{error} function attribute
-@cindex @code{warning} function attribute
-@item error ("@var{message}")
-@itemx warning ("@var{message}")
-If the @code{error} or @code{warning} attribute
-is used on a function declaration and a call to such a function
-is not eliminated through dead code elimination or other optimizations,
-an error or warning (respectively) that includes @var{message} is diagnosed.
-This is useful
-for compile-time checking, especially together with @code{__builtin_constant_p}
-and inline functions where checking the inline function arguments is not
-possible through @code{extern char [(condition) ? 1 : -1];} tricks.
+Valid arguments are constant non-negative integers and
+strings. Each numeric argument specifies an optimization @var{level}.
+Each @var{string} argument consists of one or more comma-separated
+substrings. Each substring that begins with the letter @code{O} refers
+to an optimization option such as @option{-O0} or @option{-Os}. Other
+substrings are taken as suffixes to the @code{-f} prefix jointly
+forming the name of an optimization option. @xref{Optimize Options}.
-While it is possible to leave the function undefined and thus invoke
-a link failure (to define the function with
-a message in @code{.gnu.warning*} section),
-when using these attributes the problem is diagnosed
-earlier and with exact location of the call even in presence of inline
-functions or when not emitting debugging information.
+@samp{#pragma GCC optimize} can be used to set optimization options
+for more than one function. @xref{Function Specific Option Pragmas},
+for details about the pragma.
-@cindex @code{expected_throw} function attribute
-@item expected_throw
-This attribute, attached to a function, tells the compiler the function
-is more likely to raise or propagate an exception than to return, loop
-forever, or terminate the program.
+Providing multiple strings as arguments separated by commas to specify
+multiple options is equivalent to separating the option suffixes with
+a comma (@samp{,}) within a single string. Spaces are not permitted
+within the strings.
-This hint is mostly ignored by the compiler. The only effect is when
-it's applied to @code{noreturn} functions and
-@samp{-fharden-control-flow-redundancy} is enabled, and
-@samp{-fhardcfr-check-noreturn-calls=not-always} is not overridden.
+Not every optimization option that starts with the @var{-f} prefix
+specified by the attribute necessarily has an effect on the function.
+The @code{optimize} attribute should be used for debugging purposes only.
+It is not suitable in production code.
-@cindex @code{externally_visible} function attribute
-@item externally_visible
-This attribute, attached to a global variable or function, nullifies
-the effect of the @option{-fwhole-program} command-line option, so the
-object remains visible outside the current compilation unit.
-
-If @option{-fwhole-program} is used together with @option{-flto} and
-@command{gold} is used as the linker plugin,
-@code{externally_visible} attributes are automatically added to functions
-(not variable yet due to a current @command{gold} issue)
-that are accessed outside of LTO objects according to resolution file
-produced by @command{gold}.
-For other linkers that cannot generate resolution file,
-explicit @code{externally_visible} attributes are still necessary.
-
-@cindex @code{fd_arg} function attribute
-@item fd_arg
-@itemx fd_arg (@var{N})
-The @code{fd_arg} attribute may be applied to a function that takes an open
-file descriptor at referenced argument @var{N}.
-
-It indicates that the passed filedescriptor must not have been closed.
-Therefore, when the analyzer is enabled with @option{-fanalyzer}, the
-analyzer may emit a @option{-Wanalyzer-fd-use-after-close} diagnostic
-if it detects a code path in which a function with this attribute is
-called with a closed file descriptor.
+@cindex @code{patchable_function_entry} function attribute
+@cindex extra NOP instructions at the function entry point
+@item patchable_function_entry
+In case the target's text segment can be made writable at run time by
+any means, padding the function entry with a number of NOPs can be
+used to provide a universal tool for instrumentation.
-The attribute also indicates that the file descriptor must have been checked for
-validity before usage. Therefore, analyzer may emit
-@option{-Wanalyzer-fd-use-without-check} diagnostic if it detects a code path in
-which a function with this attribute is called with a file descriptor that has
-not been checked for validity.
+The @code{patchable_function_entry} function attribute can be used to
+change the number of NOPs to any desired value. The two-value syntax
+is the same as for the command-line switch
+@option{-fpatchable-function-entry=N,M}, generating @var{N} NOPs, with
+the function entry point before the @var{M}th NOP instruction.
+@var{M} defaults to 0 if omitted e.g.@: function entry point is before
+the first NOP.
-@cindex @code{fd_arg_read} function attribute
-@item fd_arg_read
-@itemx fd_arg_read (@var{N})
-The @code{fd_arg_read} is identical to @code{fd_arg}, but with the additional
-requirement that it might read from the file descriptor, and thus, the file
-descriptor must not have been opened as write-only.
+If patchable function entries are enabled globally using the command-line
+option @option{-fpatchable-function-entry=N,M}, then you must disable
+instrumentation on all functions that are part of the instrumentation
+framework with the attribute @code{patchable_function_entry (0)}
+to prevent recursion.
-The analyzer may emit a @option{-Wanalyzer-access-mode-mismatch}
-diagnostic if it detects a code path in which a function with this
-attribute is called on a file descriptor opened with @code{O_WRONLY}.
+@cindex @code{pure} function attribute
+@cindex functions that have no side effects
+@item pure
-@cindex @code{fd_arg_write} function attribute
-@item fd_arg_write
-@itemx fd_arg_write (@var{N})
-The @code{fd_arg_write} is identical to @code{fd_arg_read} except that the
-analyzer may emit a @option{-Wanalyzer-access-mode-mismatch} diagnostic if
-it detects a code path in which a function with this attribute is called on a
-file descriptor opened with @code{O_RDONLY}.
+Calls to functions that have no observable effects on the state of
+the program other than to return a value may lend themselves to optimizations
+such as common subexpression elimination. Declaring such functions with
+the @code{pure} attribute allows GCC to avoid emitting some calls in repeated
+invocations of the function with the same argument values.
-@cindex @code{flatten} function attribute
-@item flatten
-Generally, inlining into a function is limited. For a function marked with
-this attribute, every call inside this function is inlined including the
-calls such inlining introduces to the function (but not recursive calls
-to the function itself), if possible.
-Functions declared with attribute @code{noinline} and similar are not
-inlined. Whether the function itself is considered for inlining depends
-on its size and the current inlining parameters.
+The @code{pure} attribute prohibits a function from modifying the state
+of the program that is observable by means other than inspecting
+the function's return value. However, functions declared with the @code{pure}
+attribute can safely read any non-volatile objects, and modify the value of
+objects in a way that does not affect their return value or the observable
+state of the program.
-@cindex @code{format} function attribute
-@cindex functions with @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} style arguments
-@opindex Wformat
-@item format (@var{archetype}, @var{string-index}, @var{first-to-check})
-The @code{format} attribute specifies that a function takes @code{printf},
-@code{scanf}, @code{strftime} or @code{strfmon} style arguments that
-should be type-checked against a format string. For example, the
-declaration:
+For example,
@smallexample
-extern int
-my_printf (void *my_object, const char *my_format, ...)
- __attribute__ ((format (printf, 2, 3)));
+int hash (char *) __attribute__ ((pure));
@end smallexample
@noindent
-causes the compiler to check the arguments in calls to @code{my_printf}
-for consistency with the @code{printf} style format string argument
-@code{my_format}.
+tells GCC that subsequent calls to the function @code{hash} with the same
+string can be replaced by the result of the first call provided the state
+of the program observable by @code{hash}, including the contents of the array
+itself, does not change in between. Even though @code{hash} takes a non-const
+pointer argument it must not modify the array it points to, or any other object
+whose value the rest of the program may depend on. However, the caller may
+safely change the contents of the array between successive calls to
+the function (doing so disables the optimization). The restriction also
+applies to member objects referenced by the @code{this} pointer in C++
+non-static member functions.
-The parameter @var{archetype} determines how the format string is
-interpreted, and should be @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.
-@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
-@file{msvcrt.dll} library.
-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
-argument to check against the format string. For functions
-where the arguments are not available to be checked (such as
-@code{vprintf}), specify the third parameter as zero. In this case the
-compiler only checks the format string for consistency. For
-@code{strftime} formats, the third parameter is required to be zero.
-Since non-static C++ methods have an implicit @code{this} argument, the
-arguments of such methods should be counted from two, not one, when
-giving values for @var{string-index} and @var{first-to-check}.
+Some common examples of pure functions are @code{strlen} or @code{memcmp}.
+Interesting non-pure functions are functions with infinite loops or those
+depending on volatile memory or other system resource, that may change between
+consecutive calls (such as the standard C @code{feof} function in
+a multithreading environment).
-In the example above, the format string (@code{my_format}) is the second
-argument of the function @code{my_print}, and the arguments to check
-start with the third argument, so the correct parameters for the format
-attribute are 2 and 3.
+The @code{pure} attribute imposes similar but looser restrictions on
+a function's definition than the @code{const} attribute: @code{pure}
+allows the function to read any non-volatile memory, even if it changes
+in between successive invocations of the function. Declaring the same
+function with both the @code{pure} and the @code{const} attribute is
+diagnosed. Because a pure function cannot have any observable side
+effects it does not make sense for such a function to return @code{void}.
+Declaring such a function is diagnosed.
-@opindex ffreestanding
-@opindex fno-builtin
-The @code{format} attribute allows you to identify your own functions
-that take format strings as arguments, so that GCC can check the
-calls to these functions for errors. The compiler always (unless
-@option{-ffreestanding} or @option{-fno-builtin} is used) checks formats
-for the standard library functions @code{printf}, @code{fprintf},
-@code{sprintf}, @code{scanf}, @code{fscanf}, @code{sscanf}, @code{strftime},
-@code{vprintf}, @code{vfprintf} and @code{vsprintf} whenever such
-warnings are requested (using @option{-Wformat}), so there is no need to
-modify the header file @file{stdio.h}. In C99 mode, the functions
-@code{snprintf}, @code{vsnprintf}, @code{vscanf}, @code{vfscanf} and
-@code{vsscanf} are also checked. Except in strictly conforming C
-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}.
+@cindex @code{unsequenced} function type attribute
+@cindex functions that have no side effects
+@item unsequenced
-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.
+This attribute is a GNU counterpart of the C23 @code{[[unsequenced]]}
+attribute, used to specify function pointers to effectless, idempotent,
+stateless and independent functions according to the C23 definition.
-The target may also provide additional types of format checks.
-@xref{Target Format Checks,,Format Checks Specific to Particular
-Target Machines}.
+Unlike the standard C23 attribute it can be also specified in attributes
+which appertain to function declarations and applies to the their function
+type even in that case.
-@cindex @code{format_arg} function attribute
-@opindex Wformat-nonliteral
-@item format_arg (@var{string-index})
-The @code{format_arg} attribute specifies that a function takes one or
-more format strings for a @code{printf}, @code{scanf}, @code{strftime} or
-@code{strfmon} style function and modifies it (for example, to translate
-it into another language), so the result can be passed to a
-@code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} style
-function (with the remaining arguments to the format function the same
-as they would have been for the unmodified string). Multiple
-@code{format_arg} attributes may be applied to the same function, each
-designating a distinct parameter as a format string. For example, the
-declaration:
+Unsequenced functions without pointer or reference arguments are similar
+to functions with the @code{const} attribute, except that @code{const}
+attribute also requires finiteness. So, both functions with @code{const}
+and with @code{unsequenced} attributes can be optimized by common
+subexpression elimination, but only functions with @code{const}
+attribute can be optimized by dead code elimination if their result is
+unused or is used only by dead code. Unsequenced functions without pointer
+or reference arguments with @code{void} return type are diagnosed because
+they can't store any results and don't have other observable side-effects
+either.
-@smallexample
-extern char *
-my_dgettext (char *my_domain, const char *my_format)
- __attribute__ ((format_arg (2)));
-@end smallexample
+Unsequenced functions with pointer or reference arguments can inspect
+objects through the passed pointers or references or references to pointers
+or can store additional results through those pointers or references or
+references to pointers.
-@noindent
-causes the compiler to check the arguments in calls to a @code{printf},
-@code{scanf}, @code{strftime} or @code{strfmon} type function, whose
-format string argument is a call to the @code{my_dgettext} function, for
-consistency with the format string argument @code{my_format}. If the
-@code{format_arg} attribute had not been specified, all the compiler
-could tell in such calls to format functions would be that the format
-string argument is not constant; this would generate a warning when
-@option{-Wformat-nonliteral} is used, but the calls could not be checked
-without the attribute.
+The @code{unsequenced} attribute imposes greater restrictions than
+the similar @code{reproducible} attribute and fewer restrictions than
+the @code{const} attribute, so during optimization @code{const} has
+precedence over @code{unsequenced} which has precedence over
+@code{reproducible}.
-In calls to a function declared with more than one @code{format_arg}
-attribute, each with a distinct argument value, the corresponding
-actual function arguments are checked against all format strings
-designated by the attributes. This capability is designed to support
-the GNU @code{ngettext} family of functions.
+@cindex @code{reproducible} function type attribute
+@cindex functions that have no side effects
+@item reproducible
-The parameter @var{string-index} specifies which argument is the format
-string argument (starting from one). Since non-static C++ methods have
-an implicit @code{this} argument, the arguments of such methods should
-be counted from two.
+This attribute is a GNU counterpart of the C23 @code{[[reproducible]]}
+attribute, used to specify function pointers to effectless and idempotent
+functions according to the C23 definition.
-The @code{format_arg} attribute allows you to identify your own
-functions that modify format strings, so that GCC can check the
-calls to @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon}
-type function whose operands are a call to one of your own function.
-The compiler always treats @code{gettext}, @code{dgettext}, and
-@code{dcgettext} in this manner except when strict ISO C support is
-requested by @option{-ansi} or an appropriate @option{-std} option, or
-@option{-ffreestanding} or @option{-fno-builtin}
-is used. @xref{C Dialect Options,,Options
-Controlling C Dialect}.
-
-For Objective-C dialects, the @code{format-arg} attribute may refer to an
-@code{NSString} reference for compatibility with the @code{format} attribute
-above.
+Unlike the standard C23 attribute it can be also specified in attributes
+which appertain to function declarations and applies to the their function
+type even in that case.
-The target may also allow additional types in @code{format-arg} attributes.
-@xref{Target Format Checks,,Format Checks Specific to Particular
-Target Machines}.
+Reproducible functions without pointer or reference arguments or which do
+not modify objects referenced by those pointer/reference arguments are
+similar to functions with the @code{pure} attribute, except that
+@code{pure} attribute also requires finiteness. So, both functions with
+@code{pure} and with @code{reproducible} attributes can be optimized by common
+subexpression elimination if the global state or anything reachable through
+the pointer/reference arguments isn't modified, but only functions with
+@code{pure} attribute can be optimized by dead code elimination if their result is
+unused or is used only by dead code. Reproducible functions without pointer
+or reference arguments with @code{void} return type are diagnosed because
+they can't store any results and don't have other observable side-effects
+either.
-@cindex @code{gnu_inline} function attribute
-@item gnu_inline
-This attribute should be used with a function that is also declared
-with the @code{inline} keyword. It directs GCC to treat the function
-as if it were defined in gnu90 mode even when compiling in C99 or
-gnu99 mode.
+Reproducible functions with pointer or reference arguments can store
+additional results through those pointers or references or references to
+pointers.
-If the function is declared @code{extern}, then this definition of the
-function is used only for inlining. In no case is the function
-compiled as a standalone function, not even if you take its address
-explicitly. Such an address becomes an external reference, as if you
-had only declared the function, and had not defined it. This has
-almost the effect of a macro. The way to use this is to put a
-function definition in a header file with this attribute, and put
-another copy of the function, without @code{extern}, in a library
-file. The definition in the header file causes most calls to the
-function to be inlined. If any uses of the function remain, they
-refer to the single copy in the library. Note that the two
-definitions of the functions need not be precisely the same, although
-if they do not have the same effect your program may behave oddly.
+@cindex @code{retain} function attribute
+@item retain
+For ELF targets that support the GNU or FreeBSD OSABIs, this attribute
+will save the function from linker garbage collection. To support
+this behavior, functions that have not been placed in specific sections
+(e.g. by the @code{section} attribute, or the @code{-ffunction-sections}
+option), will be placed in new, unique sections.
-In C, if the function is neither @code{extern} nor @code{static}, then
-the function is compiled as a standalone function, as well as being
-inlined where possible.
+This additional functionality requires Binutils version 2.36 or later.
-This is how GCC traditionally handled functions declared
-@code{inline}. Since ISO C99 specifies a different semantics for
-@code{inline}, this function attribute is provided as a transition
-measure and as a useful feature in its own right. This attribute is
-available in GCC 4.1.3 and later. It is available if either of the
-preprocessor macros @code{__GNUC_GNU_INLINE__} or
-@code{__GNUC_STDC_INLINE__} are defined. @xref{Inline,,An Inline
-Function is As Fast As a Macro}.
+@cindex @code{returns_nonnull} function attribute
+@item returns_nonnull
+The @code{returns_nonnull} attribute specifies that the function
+return value should be a non-null pointer. For instance, the declaration:
-In C++, this attribute does not depend on @code{extern} in any way,
-but it still requires the @code{inline} keyword to enable its special
-behavior.
+@smallexample
+extern void *
+mymalloc (size_t len) __attribute__((returns_nonnull));
+@end smallexample
-@cindex @code{hot} function attribute
-@item hot
-The @code{hot} attribute on a function is used to inform the compiler that
-the function is a hot spot of the compiled program. The function is
-optimized more aggressively and on many targets it is placed into a special
-subsection of the text section so all hot functions appear close together,
-improving locality. In C++, the @code{hot} attribute can be applied to types
-with the effect of being propagated to member functions. See
-@ref{C++ Attributes}.
+@noindent
+lets the compiler optimize callers based on the knowledge
+that the return value will never be null.
-When profile feedback is available, via @option{-fprofile-use}, hot functions
-are automatically detected and this attribute is ignored.
+@cindex @code{returns_twice} function attribute
+@cindex functions that return more than once
+@item returns_twice
+The @code{returns_twice} attribute tells the compiler that a function may
+return more than one time. The compiler ensures that all registers
+are dead before calling such a function and emits a warning about
+the variables that may be clobbered after the second return from the
+function. Examples of such functions are @code{setjmp} and @code{vfork}.
+The @code{longjmp}-like counterpart of such function, if any, might need
+to be marked with the @code{noreturn} attribute.
-@cindex @code{ifunc} function attribute
-@cindex indirect functions
-@cindex functions that are dynamically resolved
-@item ifunc ("@var{resolver}")
-The @code{ifunc} attribute is used to mark a function as an indirect
-function using the STT_GNU_IFUNC symbol type extension to the ELF
-standard. This allows the resolution of the symbol value to be
-determined dynamically at load time, and an optimized version of the
-routine to be selected for the particular processor or other system
-characteristics determined then. To use this attribute, first define
-the implementation functions available, and a resolver function that
-returns a pointer to the selected implementation function. The
-implementation functions' declarations must match the API of the
-function being implemented. The resolver should be declared to
-be a function taking no arguments and returning a pointer to
-a function of the same type as the implementation. For example:
+@cindex @code{section} function attribute
+@cindex functions in arbitrary sections
+@item section ("@var{section-name}")
+Normally, the compiler places the code it generates in the @code{text} section.
+Sometimes, however, you need additional sections, or you need certain
+particular functions to appear in special sections. The @code{section}
+attribute specifies that a function lives in a particular section.
+For example, the declaration:
@smallexample
-void *my_memcpy (void *dst, const void *src, size_t len)
-@{
- @dots{}
- return dst;
-@}
-
-static void * (*resolve_memcpy (void))(void *, const void *, size_t)
-@{
- return my_memcpy; // we will just always select this routine
-@}
+extern void foobar (void) __attribute__ ((section ("bar")));
@end smallexample
@noindent
-The exported header file declaring the function the user calls would
-contain:
+puts the function @code{foobar} in the @code{bar} section.
-@smallexample
-extern void *memcpy (void *, const void *, size_t);
-@end smallexample
+Some file formats do not support arbitrary sections so the @code{section}
+attribute is not available on all platforms.
+If you need to map the entire contents of a module to a particular
+section, consider using the facilities of the linker instead.
-@noindent
-allowing the user to call @code{memcpy} as a regular function, unaware of
-the actual implementation. Finally, the indirect function needs to be
-defined in the same translation unit as the resolver function:
+@cindex @code{sentinel} function attribute
+@item sentinel
+@itemx sentinel (@var{position})
+This function attribute indicates that an argument in a call to the function
+is expected to be an explicit @code{NULL}. The attribute is only valid on
+variadic functions. By default, the sentinel is expected to be the last
+argument of the function call. If the optional @var{position} argument
+is specified to the attribute, the sentinel must be located at
+@var{position} counting backwards from the end of the argument list.
@smallexample
-void *memcpy (void *, const void *, size_t)
- __attribute__ ((ifunc ("resolve_memcpy")));
+__attribute__ ((sentinel))
+is equivalent to
+__attribute__ ((sentinel(0)))
@end smallexample
-In C++, the @code{ifunc} attribute takes a string that is the mangled name
-of the resolver function. A C++ resolver for a non-static member function
-of class @code{C} should be declared to return a pointer to a non-member
-function taking pointer to @code{C} as the first argument, followed by
-the same arguments as of the implementation function. G++ checks
-the signatures of the two functions and issues
-a @option{-Wattribute-alias} warning for mismatches. To suppress a warning
-for the necessary cast from a pointer to the implementation member function
-to the type of the corresponding non-member function use
-the @option{-Wno-pmf-conversions} option. For example:
+The attribute is automatically set with a position of 0 for the built-in
+functions @code{execl} and @code{execlp}. The built-in function
+@code{execle} has the attribute set with a position of 1.
-@smallexample
-class S
-@{
-private:
- int debug_impl (int);
- int optimized_impl (int);
+A valid @code{NULL} in this context is defined as zero with any object
+pointer type. If your system defines the @code{NULL} macro with
+an integer type then you need to add an explicit cast. During
+installation GCC replaces the system @code{<stddef.h>} header with
+a copy that redefines NULL appropriately.
- typedef int Func (S*, int);
+The warnings for missing or incorrect sentinels are enabled with
+@option{-Wformat}.
- static Func* resolver ();
-public:
+@cindex @code{simd} function attribute
+@item simd
+@itemx simd("@var{mask}")
+This attribute enables creation of one or more function versions that
+can process multiple arguments using SIMD instructions from a
+single invocation. Specifying this attribute allows compiler to
+assume that such versions are available at link time (provided
+in the same or another translation unit). Generated versions are
+target-dependent and described in the corresponding Vector ABI document. For
+x86_64 target this document can be found
+@w{@uref{https://sourceware.org/glibc/wiki/libmvec?action=AttachFile&do=view&target=VectorABI.txt,here}}.
- int interface (int);
-@};
+The optional argument @var{mask} may have the value
+@code{notinbranch} or @code{inbranch},
+and instructs the compiler to generate non-masked or masked
+clones correspondingly. By default, all clones are generated.
-int S::debug_impl (int) @{ /* @r{@dots{}} */ @}
-int S::optimized_impl (int) @{ /* @r{@dots{}} */ @}
+If the attribute is specified and @code{#pragma omp declare simd} is
+present on a declaration and the @option{-fopenmp} or @option{-fopenmp-simd}
+switch is specified, then the attribute is ignored.
-S::Func* S::resolver ()
-@{
- int (S::*pimpl) (int)
- = getenv ("DEBUG") ? &S::debug_impl : &S::optimized_impl;
+@cindex @code{stack_protect} function attribute
+@item stack_protect
+This attribute adds stack protection code to the function if
+flags @option{-fstack-protector}, @option{-fstack-protector-strong}
+or @option{-fstack-protector-explicit} are set.
- // Cast triggers -Wno-pmf-conversions.
- return reinterpret_cast<Func*>(pimpl);
-@}
+@cindex @code{symver} function attribute
+@item symver ("@var{name2}@@@var{nodename}")
+On ELF targets this attribute creates a symbol version. The @var{name2} part
+of the parameter is the actual name of the symbol by which it will be
+externally referenced. The @code{nodename} portion should be the name of a
+node specified in the version script supplied to the linker when building a
+shared library. Versioned symbol must be defined and must be exported with
+default visibility.
-int S::interface (int) __attribute__ ((ifunc ("_ZN1S8resolverEv")));
+@smallexample
+__attribute__ ((__symver__ ("foo@@VERS_1"))) int
+foo_v1 (void)
+@{
+@}
@end smallexample
-Indirect functions cannot be weak. Binutils version 2.20.1 or higher
-and GNU C Library version 2.11.1 are required to use this feature.
+Will produce a @code{.symver foo_v1, foo@@VERS_1} directive in the assembler
+output.
-@cindex @code{interrupt_handler} function attribute
-@cindex @code{interrupt} function attribute
-@item interrupt
-@itemx interrupt_handler
-Many GCC back ends support attributes to indicate that a function is
-an interrupt handler, which tells the compiler to generate function
-entry and exit sequences that differ from those from regular
-functions. The exact syntax and behavior are target-specific;
-refer to the following subsections for details.
+One can also define multiple version for a given symbol
+(starting from binutils 2.35).
-@cindex @code{leaf} function attribute
-@item leaf
-Calls to external functions with this attribute must return to the
-current compilation unit only by return or by exception handling. In
-particular, a leaf function is not allowed to invoke callback functions
-passed to it from the current compilation unit, directly call functions
-exported by the unit, or @code{longjmp} into the unit. Leaf functions
-might still call functions from other compilation units and thus they
-are not necessarily leaf in the sense that they contain no function
-calls at all.
+@smallexample
+__attribute__ ((__symver__ ("foo@@VERS_2"), __symver__ ("foo@@VERS_3")))
+int symver_foo_v1 (void)
+@{
+@}
+@end smallexample
-The attribute is intended for library functions to improve dataflow
-analysis. The compiler takes the hint that any data not escaping the
-current compilation unit cannot be used or modified by the leaf
-function. For example, the @code{sin} function is a leaf function, but
-@code{qsort} is not.
+This example creates a symbol name @code{symver_foo_v1}
+which will be version @code{VERS_2} and @code{VERS_3} of @code{foo}.
-Note that leaf functions might indirectly run a signal handler defined
-in the current compilation unit that uses static variables. Similarly,
-when lazy symbol resolution is in effect, leaf functions might invoke
-indirect functions whose resolver function or implementation function is
-defined in the current compilation unit and uses static variables. There
-is no standard-compliant way to write such a signal handler, resolver
-function, or implementation function, and the best that you can do is to
-remove the @code{leaf} attribute or mark all such static variables
-@code{volatile}. Lastly, for ELF-based systems that support symbol
-interposition, care should be taken that functions defined in the
-current compilation unit do not unexpectedly interpose other symbols
-based on the defined standards mode and defined feature test macros;
-otherwise an inadvertent callback would be added.
+If you have an older release of binutils, then symbol alias needs to
+be used:
-The attribute has no effect on functions defined within the current
-compilation unit. This is to allow easy merging of multiple compilation
-units into one, for example, by using the link-time optimization. For
-this reason the attribute is not allowed on types to annotate indirect
-calls.
+@smallexample
+__attribute__ ((__symver__ ("foo@@VERS_2")))
+int foo_v1 (void)
+@{
+ return 0;
+@}
-@cindex @code{malloc} function attribute
-@cindex functions that behave like malloc
-@item malloc
-@item malloc (@var{deallocator})
-@item malloc (@var{deallocator}, @var{ptr-index})
-Attribute @code{malloc} indicates that a function is @code{malloc}-like,
-i.e., that the pointer @var{P} returned by the function cannot alias any
-other pointer valid when the function returns, and moreover no
-pointers to valid objects occur in any storage addressed by @var{P}. In
-addition, GCC predicts that a function with the attribute returns
-non-null in most cases.
+__attribute__ ((__symver__ ("foo@@VERS_3")))
+__attribute__ ((alias ("foo_v1")))
+int symver_foo_v1 (void);
+@end smallexample
-Independently, the form of the attribute with one or two arguments
-associates @code{deallocator} as a suitable deallocation function for
-pointers returned from the @code{malloc}-like function. @var{ptr-index}
-denotes the positional argument to which when the pointer is passed in
-calls to @code{deallocator} has the effect of deallocating it.
+Finally if the parameter is @code{"@var{name2}@@@@@var{nodename}"} then in
+addition to creating a symbol version (as if
+@code{"@var{name2}@@@var{nodename}"} was used) the version will be also used
+to resolve @var{name2} by the linker.
-Using the attribute with no arguments is designed to improve optimization
-by relying on the aliasing property it implies. Functions like @code{malloc}
-and @code{calloc} have this property because they return a pointer to
-uninitialized or zeroed-out, newly obtained storage. However, functions
-like @code{realloc} do not have this property, as they may return pointers
-to storage containing pointers to existing objects. Additionally, since
-all such functions are assumed to return null only infrequently, callers
-can be optimized based on that assumption.
+@cindex @code{tainted_args} function attribute
+@item tainted_args
+The @code{tainted_args} attribute is used to specify that a function is called
+in a way that requires sanitization of its arguments, such as a system
+call in an operating system kernel. Such a function can be considered part
+of the ``attack surface'' of the program. The attribute can be used both
+on function declarations, and on field declarations containing function
+pointers. In the latter case, any function used as an initializer of
+such a callback field will be treated as being called with tainted
+arguments.
-Associating a function with a @var{deallocator} helps detect calls to
-mismatched allocation and deallocation functions and diagnose them under
-the control of options such as @option{-Wmismatched-dealloc}. It also
-makes it possible to diagnose attempts to deallocate objects that were not
-allocated dynamically, by @option{-Wfree-nonheap-object}. To indicate
-that an allocation function both satisfies the nonaliasing property and
-has a deallocator associated with it, both the plain form of the attribute
-and the one with the @var{deallocator} argument must be used. The same
-function can be both an allocator and a deallocator. Since inlining one
-of the associated functions but not the other could result in apparent
-mismatches, this form of attribute @code{malloc} is not accepted on inline
-functions. For the same reason, using the attribute prevents both
-the allocation and deallocation functions from being expanded inline.
+The analyzer will pay particular attention to such functions when
+@option{-fanalyzer} is supplied, potentially issuing warnings guarded by
+@option{-Wanalyzer-tainted-allocation-size},
+@option{-Wanalyzer-tainted-array-index},
+@option{-Wanalyzer-tainted-divisor},
+@option{-Wanalyzer-tainted-offset},
+and @option{-Wanalyzer-tainted-size}.
-For example, besides stating that the functions return pointers that do
-not alias any others, the following declarations make @code{fclose}
-a suitable deallocator for pointers returned from all functions except
-@code{popen}, and @code{pclose} as the only suitable deallocator for
-pointers returned from @code{popen}. The deallocator functions must
-be declared before they can be referenced in the attribute.
+@cindex @code{target} function attribute
+@item target (@var{string}, @dots{})
+Multiple target back ends implement the @code{target} attribute
+to specify that a function is to
+be compiled with different target options than specified on the
+command line. The original target command-line options are ignored.
+One or more strings can be provided as arguments.
+Each string consists of one or more comma-separated suffixes to
+the @code{-m} prefix jointly forming the name of a machine-dependent
+option. @xref{Submodel Options,,Machine-Dependent Options}.
-@smallexample
-int fclose (FILE*);
-int pclose (FILE*);
+The @code{target} attribute can be used for instance to have a function
+compiled with a different ISA (instruction set architecture) than the
+default. @samp{#pragma GCC target} can be used to specify target-specific
+options for more than one function. @xref{Function Specific Option Pragmas},
+for details about the pragma.
-__attribute__ ((malloc, malloc (fclose, 1)))
- FILE* fdopen (int, const char*);
-__attribute__ ((malloc, malloc (fclose, 1)))
- FILE* fopen (const char*, const char*);
-__attribute__ ((malloc, malloc (fclose, 1)))
- FILE* fmemopen(void *, size_t, const char *);
-__attribute__ ((malloc, malloc (pclose, 1)))
- FILE* popen (const char*, const char*);
-__attribute__ ((malloc, malloc (fclose, 1)))
- FILE* tmpfile (void);
+For instance, on an x86, you could declare one function with the
+@code{target("sse4.1,arch=core2")} attribute and another with
+@code{target("sse4a,arch=amdfam10")}. This is equivalent to
+compiling the first function with @option{-msse4.1} and
+@option{-march=core2} options, and the second function with
+@option{-msse4a} and @option{-march=amdfam10} options. It is up to you
+to make sure that a function is only invoked on a machine that
+supports the particular ISA it is compiled for (for example by using
+@code{cpuid} on x86 to determine what feature bits and architecture
+family are used).
+
+@smallexample
+int core2_func (void) __attribute__ ((__target__ ("arch=core2")));
+int sse3_func (void) __attribute__ ((__target__ ("sse3")));
@end smallexample
-The warnings guarded by @option{-fanalyzer} respect allocation and
-deallocation pairs marked with the @code{malloc}. In particular:
+Providing multiple strings as arguments separated by commas to specify
+multiple options is equivalent to separating the option suffixes with
+a comma (@samp{,}) within a single string. Spaces are not permitted
+within the strings.
-@itemize @bullet
+The options supported are specific to each target; refer to @ref{x86
+Function Attributes}, @ref{PowerPC Function Attributes},
+@ref{ARM Function Attributes}, @ref{AArch64 Function Attributes},
+and @ref{S/390 Function Attributes} for details.
-@item
-The analyzer emits a @option{-Wanalyzer-mismatching-deallocation}
-diagnostic if there is an execution path in which the result of an
-allocation call is passed to a different deallocator.
+@cindex @code{target_clones} function attribute
+@item target_clones (@var{options})
+The @code{target_clones} attribute is used to specify that a function
+be cloned into multiple versions compiled with different target options
+than specified on the command line. The supported options and restrictions
+are the same as for @code{target} attribute.
-@item
-The analyzer emits a @option{-Wanalyzer-double-free}
-diagnostic if there is an execution path in which a value is passed
-more than once to a deallocation call.
+For instance, on an x86, you could compile a function with
+@code{target_clones("sse4.1,avx")}. GCC creates two function clones,
+one compiled with @option{-msse4.1} and another with @option{-mavx}.
-@item
-The analyzer considers the possibility that an allocation function
-could fail and return null. If there are
-execution paths in which an unchecked result of an allocation call is
-dereferenced or passed to a function requiring a non-null argument,
-it emits
-@option{-Wanalyzer-possible-null-dereference} and
-@option{-Wanalyzer-possible-null-argument} diagnostics.
-If the allocator always returns non-null, use
-@code{__attribute__ ((returns_nonnull))} to suppress these warnings.
-For example:
-@smallexample
-char *xstrdup (const char *)
- __attribute__((malloc (free), returns_nonnull));
-@end smallexample
+On a PowerPC, you can compile a function with
+@code{target_clones("cpu=power9,default")}. GCC will create two
+function clones, one compiled with @option{-mcpu=power9} and another
+with the default options. GCC must be configured to use GLIBC 2.23 or
+newer in order to use the @code{target_clones} attribute.
-@item
-The analyzer emits a @option{-Wanalyzer-use-after-free}
-diagnostic if there is an execution path in which the memory passed
-by pointer to a deallocation call is used after the deallocation.
+It also creates a resolver function (see
+the @code{ifunc} attribute above) that dynamically selects a clone
+suitable for current architecture. The resolver is created only if there
+is a usage of a function with @code{target_clones} attribute.
-@item
-The analyzer emits a @option{-Wanalyzer-malloc-leak} diagnostic if
-there is an execution path in which the result of an allocation call
-is leaked (without being passed to the deallocation function).
+Note that any subsequent call of a function without @code{target_clone}
+from a @code{target_clone} caller will not lead to copying
+(target clone) of the called function.
+If you want to enforce such behavior,
+we recommend declaring the calling function with the @code{flatten} attribute?
-@item
-The analyzer emits a @option{-Wanalyzer-free-of-non-heap} diagnostic
-if a deallocation function is used on a global or on-stack variable.
+@cindex @code{unavailable} function attribute
+@item unavailable
+@itemx unavailable (@var{msg})
+The @code{unavailable} attribute results in an error if the function
+is used anywhere in the source file. This is useful when identifying
+functions that have been removed from a particular variation of an
+interface. Other than emitting an error rather than a warning, the
+@code{unavailable} attribute behaves in the same manner as
+@code{deprecated}.
-@end itemize
+The @code{unavailable} attribute can also be used for variables and
+types (@pxref{Variable Attributes}, @pxref{Type Attributes}.)
-The analyzer assumes that deallocators can gracefully handle the null
-pointer. If this is not the case, the deallocator can be marked with
-@code{__attribute__((nonnull))} so that @option{-fanalyzer} can emit
-a @option{-Wanalyzer-possible-null-argument} diagnostic for code paths
-in which the deallocator is called with null.
+@cindex @code{unused} function attribute
+@item unused
+This attribute, attached to a function, means that the function is meant
+to be possibly unused. GCC does not produce a warning for this
+function.
-@cindex @code{no_icf} function attribute
-@item no_icf
-This function attribute prevents a functions from being merged with another
-semantically equivalent function.
+@cindex @code{used} function attribute
+@item used
+This attribute, attached to a function, means that code must be emitted
+for the function even if it appears that the function is not referenced.
+This is useful, for example, when the function is referenced only in
+inline assembly.
-@cindex @code{no_instrument_function} function attribute
-@opindex finstrument-functions
-@opindex p
-@opindex pg
-@item no_instrument_function
-If any of @option{-finstrument-functions}, @option{-p}, or @option{-pg} are
-given, profiling function calls are
-generated at entry and exit of most user-compiled functions.
-Functions with this attribute are not so instrumented.
-
-@cindex @code{no_profile_instrument_function} function attribute
-@item no_profile_instrument_function
-The @code{no_profile_instrument_function} attribute on functions is used
-to inform the compiler that it should not process any profile feedback based
-optimization code instrumentation.
+When applied to a member function of a C++ class template, the
+attribute also means that the function is instantiated if the
+class itself is instantiated.
-@cindex @code{no_reorder} function attribute
-@item no_reorder
-Do not reorder functions or variables marked @code{no_reorder}
-against each other or top level assembler statements the executable.
-The actual order in the program will depend on the linker command
-line. Static variables marked like this are also not removed.
-This has a similar effect
-as the @option{-fno-toplevel-reorder} option, but only applies to the
-marked symbols.
+@cindex @code{visibility} function attribute
+@item visibility ("@var{visibility_type}")
+This attribute affects the linkage of the declaration to which it is attached.
+It can be applied to variables (@pxref{Common Variable Attributes}) and types
+(@pxref{Common Type Attributes}) as well as functions.
-@cindex @code{no_sanitize} function attribute
-@item no_sanitize ("@var{sanitize_option}")
-The @code{no_sanitize} attribute on functions is used
-to inform the compiler that it should not do sanitization of any option
-mentioned in @var{sanitize_option}. A list of values acceptable by
-the @option{-fsanitize} option can be provided.
+There are four supported @var{visibility_type} values: default,
+hidden, protected or internal visibility.
@smallexample
-void __attribute__ ((no_sanitize ("alignment", "object-size")))
+void __attribute__ ((visibility ("protected")))
f () @{ /* @r{Do something.} */; @}
-void __attribute__ ((no_sanitize ("alignment,object-size")))
-g () @{ /* @r{Do something.} */; @}
+int i __attribute__ ((visibility ("hidden")));
@end smallexample
-@cindex @code{no_sanitize_address} function attribute
-@item no_sanitize_address
-@itemx no_address_safety_analysis
-The @code{no_sanitize_address} attribute on functions is used
-to inform the compiler that it should not instrument memory accesses
-in the function when compiling with the @option{-fsanitize=address} option.
-The @code{no_address_safety_analysis} is a deprecated alias of the
-@code{no_sanitize_address} attribute, new code should use
-@code{no_sanitize_address}.
+The possible values of @var{visibility_type} correspond to the
+visibility settings in the ELF gABI.
-@cindex @code{no_sanitize_thread} function attribute
-@item no_sanitize_thread
-The @code{no_sanitize_thread} attribute on functions is used
-to inform the compiler that it should not instrument memory accesses
-in the function when compiling with the @option{-fsanitize=thread} option.
+@table @code
+@c keep this list of visibilities in alphabetical order.
-@cindex @code{no_sanitize_undefined} function attribute
-@item no_sanitize_undefined
-The @code{no_sanitize_undefined} attribute on functions is used
-to inform the compiler that it should not check for undefined behavior
-in the function when compiling with the @option{-fsanitize=undefined} option.
+@item default
+Default visibility is the normal case for the object file format.
+This value is available for the visibility attribute to override other
+options that may change the assumed visibility of entities.
-@cindex @code{no_sanitize_coverage} function attribute
-@item no_sanitize_coverage
-The @code{no_sanitize_coverage} attribute on functions is used
-to inform the compiler that it should not do coverage-guided
-fuzzing code instrumentation (@option{-fsanitize-coverage}).
+On ELF, default visibility means that the declaration is visible to other
+modules and, in shared libraries, means that the declared entity may be
+overridden.
-@cindex @code{no_split_stack} function attribute
-@opindex fsplit-stack
-@item no_split_stack
-If @option{-fsplit-stack} is given, functions have a small
-prologue which decides whether to split the stack. Functions with the
-@code{no_split_stack} attribute do not have that prologue, and thus
-may run with only a small amount of stack space available.
+On Darwin, default visibility means that the declaration is visible to
+other modules.
-@cindex @code{no_stack_limit} function attribute
-@item no_stack_limit
-This attribute locally overrides the @option{-fstack-limit-register}
-and @option{-fstack-limit-symbol} command-line options; it has the effect
-of disabling stack limit checking in the function it applies to.
+Default visibility corresponds to ``external linkage'' in the language.
-@cindex @code{no_stack_protector} function attribute
-@item no_stack_protector
-This attribute prevents stack protection code for the function.
+@item hidden
+Hidden visibility indicates that the entity declared has a new
+form of linkage, which we call ``hidden linkage''. Two
+declarations of an object with hidden linkage refer to the same object
+if they are in the same shared object.
-@cindex @code{noclone} function attribute
-@item noclone
-This function attribute prevents a function from being considered for
-cloning---a mechanism that produces specialized copies of functions
-and which is (currently) performed by interprocedural constant
-propagation.
+@item internal
+Internal visibility is like hidden visibility, but with additional
+processor specific semantics. Unless otherwise specified by the
+psABI, GCC defines internal visibility to mean that a function is
+@emph{never} called from another module. Compare this with hidden
+functions which, while they cannot be referenced directly by other
+modules, can be referenced indirectly via function pointers. By
+indicating that a function cannot be called from outside the module,
+GCC may for instance omit the load of a PIC register since it is known
+that the calling function loaded the correct value.
-@cindex @code{noinline} function attribute
-@item noinline
-This function attribute prevents a function from being considered for
-inlining. It also disables some other interprocedural optimizations; it's
-preferable to use the more comprehensive @code{noipa} attribute instead
-if that is your goal.
+@item protected
+Protected visibility is like default visibility except that it
+indicates that references within the defining module bind to the
+definition in that module. That is, the declared entity cannot be
+overridden by another module.
-@c Don't enumerate the optimizations by name here; we try to be
-@c future-compatible with this mechanism.
-Even if a function is declared with the @code{noinline} attribute,
-there are optimizations other than inlining that can cause calls to be
-optimized away if it does not have side effects, although the function
-call is live. To keep such calls from being optimized away, put
+@end table
-@smallexample
-asm ("");
-@end smallexample
+All visibilities are supported on many, but not all, ELF targets
+(supported when the assembler supports the @samp{.visibility}
+pseudo-op). Default visibility is supported everywhere. Hidden
+visibility is supported on Darwin targets.
-@noindent
-(@pxref{Extended Asm}) in the called function, to serve as a special
-side effect.
+The visibility attribute should be applied only to declarations that
+would otherwise have external linkage. The attribute should be applied
+consistently, so that the same entity should not be declared with
+different settings of the attribute.
-@cindex @code{noipa} function attribute
-@item noipa
-Disable interprocedural optimizations between the function with this
-attribute and its callers, as if the body of the function is not available
-when optimizing callers and the callers are unavailable when optimizing
-the body. This attribute implies @code{noinline}, @code{noclone} and
-@code{no_icf} attributes. However, this attribute is not equivalent
-to a combination of other attributes, because its purpose is to suppress
-existing and future optimizations employing interprocedural analysis,
-including those that do not have an attribute suitable for disabling
-them individually.
+In C++, the visibility attribute applies to types as well as functions
+and objects, because in C++ types have linkage. A class must not have
+greater visibility than its non-static data member types and bases,
+and class members default to the visibility of their class. Also, a
+declaration without explicit visibility is limited to the visibility
+of its type.
-@cindex @code{nonnull} function attribute
-@cindex functions with non-null pointer arguments
-@item nonnull
-@itemx nonnull (@var{arg-index}, @dots{})
-The @code{nonnull} attribute may be applied to a function that takes at
-least one argument of a pointer type. It indicates that the referenced
-arguments must be non-null pointers. For instance, the declaration:
+In C++, you can mark member functions and static member variables of a
+class with the visibility attribute. This is useful if you know a
+particular method or static member variable should only be used from
+one shared object; then you can mark it hidden while the rest of the
+class has default visibility. Care must be taken to avoid breaking
+the One Definition Rule; for example, it is usually not useful to mark
+an inline method as hidden without marking the whole class as hidden.
+
+A C++ namespace declaration can also have the visibility attribute.
@smallexample
-extern void *
-my_memcpy (void *dest, const void *src, size_t len)
- __attribute__((nonnull (1, 2)));
+namespace nspace1 __attribute__ ((visibility ("protected")))
+@{ /* @r{Do something.} */; @}
@end smallexample
-@noindent
-informs the compiler that, in calls to @code{my_memcpy}, arguments
-@var{dest} and @var{src} must be non-null.
-
-The attribute has an effect both on functions calls and function definitions.
+This attribute applies only to the particular namespace body, not to
+other definitions of the same namespace; it is equivalent to using
+@samp{#pragma GCC visibility} before and after the namespace
+definition (@pxref{Visibility Pragmas}).
-For function calls:
-@itemize @bullet
-@item If the compiler determines that a null pointer is
-passed in an argument slot marked as non-null, and the
-@option{-Wnonnull} option is enabled, a warning is issued.
-@xref{Warning Options}.
-@item The @option{-fisolate-erroneous-paths-attribute} option can be
-specified to have GCC transform calls with null arguments to non-null
-functions into traps. @xref{Optimize Options}.
-@item The compiler may also perform optimizations based on the
-knowledge that certain function arguments cannot be null. These
-optimizations can be disabled by the
-@option{-fno-delete-null-pointer-checks} option. @xref{Optimize Options}.
-@end itemize
+In C++, if a template argument has limited visibility, this
+restriction is implicitly propagated to the template instantiation.
+Otherwise, template instantiations and specializations default to the
+visibility of their template.
-For function definitions:
-@itemize @bullet
-@item If the compiler determines that a function parameter that is
-marked with nonnull is compared with null, and
-@option{-Wnonnull-compare} option is enabled, a warning is issued.
-@xref{Warning Options}.
-@item The compiler may also perform optimizations based on the
-knowledge that @code{nonnull} parameters cannot be null. This can
-currently not be disabled other than by removing the nonnull
-attribute.
-@end itemize
+If both the template and enclosing class have explicit visibility, the
+visibility from the template is used.
-If no @var{arg-index} is given to the @code{nonnull} attribute,
-all pointer arguments are marked as non-null. To illustrate, the
-following declaration is equivalent to the previous example:
+@cindex @code{warn_unused_result} function attribute
+@item warn_unused_result
+The @code{warn_unused_result} attribute causes a warning to be emitted
+if a caller of the function with this attribute does not use its
+return value. This is useful for functions where not checking
+the result is either a security problem or always a bug, such as
+@code{realloc}.
@smallexample
-extern void *
-my_memcpy (void *dest, const void *src, size_t len)
- __attribute__((nonnull));
+int fn () __attribute__ ((warn_unused_result));
+int foo ()
+@{
+ if (fn () < 0) return -1;
+ fn ();
+ return 0;
+@}
@end smallexample
-@cindex @code{nonnull_if_nonzero} function attribute
-@item nonnull_if_nonzero
-@itemx nonnull_if_nonzero (@var{arg-index}, @var{arg2-index})
-The @code{nonnull_if_nonzero} attribute is a conditional version of the
-@code{nonnull} attribute. It has two 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.
-
-@smallexample
-extern void *
-my_memcpy (void *dest, const void *src, size_t len)
- __attribute__((nonnull (1, 2)));
-extern void *
-my_memcpy2 (void *dest, const void *src, size_t len)
- __attribute__((nonnull_if_nonzero (1, 3),
- nonnull_if_nonzero (2, 3)));
-@end smallexample
+@noindent
+results in warning on line 5.
-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
-used on declarations which have e.g.@: an exception for zero sizes,
-in which case null may be passed.
+@cindex @code{weak} function attribute
+@item weak
+The @code{weak} attribute causes a declaration of an external symbol
+to be emitted as a weak symbol rather than a global. This is primarily
+useful in defining library functions that can be overridden in user code,
+though it can also be used with non-function declarations. The overriding
+symbol must have the same type as the weak symbol. In addition, if it
+designates a variable it must also have the same size and alignment as
+the weak symbol. Weak symbols are supported for ELF targets, and also
+for a.out targets when using the GNU assembler and linker.
-@cindex @code{noplt} function attribute
-@item noplt
-The @code{noplt} attribute is the counterpart to option @option{-fno-plt}.
-Calls to functions marked with this attribute in position-independent code
-do not use the PLT.
+@cindex @code{weakref} function attribute
+@item weakref
+@itemx weakref ("@var{target}")
+The @code{weakref} attribute marks a declaration as a weak reference.
+Without arguments, it should be accompanied by an @code{alias} attribute
+naming the target symbol. Alternatively, @var{target} may be given as
+an argument to @code{weakref} itself, naming the target definition of
+the alias. The @var{target} must have the same type as the declaration.
+In addition, if it designates a variable it must also have the same size
+and alignment as the declaration. In either form of the declaration
+@code{weakref} implicitly marks the declared symbol as @code{weak}. Without
+a @var{target} given as an argument to @code{weakref} or to @code{alias},
+@code{weakref} is equivalent to @code{weak} (in that case the declaration
+may be @code{extern}).
@smallexample
-@group
-/* Externally defined function foo. */
-int foo () __attribute__ ((noplt));
-
-int
-main (/* @r{@dots{}} */)
-@{
- /* @r{@dots{}} */
- foo ();
- /* @r{@dots{}} */
-@}
-@end group
-@end smallexample
+/* Given the declaration: */
+extern int y (void);
-The @code{noplt} attribute on function @code{foo}
-tells the compiler to assume that
-the function @code{foo} is externally defined and that the call to
-@code{foo} must avoid the PLT
-in position-independent code.
+/* the following... */
+static int x (void) __attribute__ ((weakref ("y")));
-In position-dependent code, a few targets also convert calls to
-functions that are marked to not use the PLT to use the GOT instead.
+/* is equivalent to... */
+static int x (void) __attribute__ ((weakref, alias ("y")));
-@cindex @code{noreturn} function attribute
-@cindex functions that never return
-@item noreturn
-A few standard library functions, such as @code{abort} and @code{exit},
-cannot return. GCC knows this automatically. Some programs define
-their own functions that never return. You can declare them
-@code{noreturn} to tell the compiler this fact. For example,
+/* or, alternatively, to... */
+static int x (void) __attribute__ ((weakref));
+static int x (void) __attribute__ ((alias ("y")));
+@end smallexample
-@smallexample
-@group
-void fatal () __attribute__ ((noreturn));
+A weak reference is an alias that does not by itself require a
+definition to be given for the target symbol. If the target symbol is
+only referenced through weak references, then it becomes a @code{weak}
+undefined symbol. If it is directly referenced, however, then such
+strong references prevail, and a definition is required for the
+symbol, not necessarily in the same translation unit.
-void
-fatal (/* @r{@dots{}} */)
-@{
- /* @r{@dots{}} */ /* @r{Print error message.} */ /* @r{@dots{}} */
- exit (1);
-@}
-@end group
-@end smallexample
+The effect is equivalent to moving all references to the alias to a
+separate translation unit, renaming the alias to the aliased symbol,
+declaring it as weak, compiling the two separate translation units and
+performing a link with relocatable output (i.e.@: @code{ld -r}) on them.
-The @code{noreturn} keyword tells the compiler to assume that
-@code{fatal} cannot return. It can then optimize without regard to what
-would happen if @code{fatal} ever did return. This makes slightly
-better code. More importantly, it helps avoid spurious warnings of
-uninitialized variables.
+A declaration to which @code{weakref} is attached and that is associated
+with a named @code{target} must be @code{static}.
-The @code{noreturn} keyword does not affect the exceptional path when that
-applies: a @code{noreturn}-marked function may still return to the caller
-by throwing an exception or calling @code{longjmp}.
+@cindex @code{zero_call_used_regs} function attribute
+@item zero_call_used_regs ("@var{choice}")
-In order to preserve backtraces, GCC will never turn calls to
-@code{noreturn} functions into tail calls.
+The @code{zero_call_used_regs} attribute causes the compiler to zero
+a subset of all call-used registers@footnote{A ``call-used'' register
+is a register whose contents can be changed by a function call;
+therefore, a caller cannot assume that the register has the same contents
+on return from the function as it had before calling the function. Such
+registers are also called ``call-clobbered'', ``caller-saved'', or
+``volatile''.} at function return.
+This is used to increase program security by either mitigating
+Return-Oriented Programming (ROP) attacks or preventing information leakage
+through registers.
-Do not assume that registers saved by the calling function are
-restored before calling the @code{noreturn} function.
+In order to satisfy users with different security needs and control the
+run-time overhead at the same time, the @var{choice} parameter provides a
+flexible way to choose the subset of the call-used registers to be zeroed.
+The four basic values of @var{choice} are:
-It does not make sense for a @code{noreturn} function to have a return
-type other than @code{void}.
+@itemize @bullet
+@item
+@samp{skip} doesn't zero any call-used registers.
-@cindex @code{nothrow} function attribute
-@item nothrow
-The @code{nothrow} attribute is used to inform the compiler that a
-function cannot throw an exception. For example, most functions in
-the standard C library can be guaranteed not to throw an exception
-with the notable exceptions of @code{qsort} and @code{bsearch} that
-take function pointer arguments.
+@item
+@samp{used} only zeros call-used registers that are used in the function.
+A ``used'' register is one whose content has been set or referenced in
+the function.
-@cindex @code{null_terminated_string_arg} function attribute
-@item null_terminated_string_arg
-@itemx null_terminated_string_arg (@var{N})
-The @code{null_terminated_string_arg} attribute may be applied to a
-function that takes a @code{char *} or @code{const char *} at
-referenced argument @var{N}.
+@item
+@samp{all} zeros all call-used registers.
-It indicates that the passed argument must be a C-style null-terminated
-string. Specifically, the presence of the attribute implies that, if
-the pointer is non-null, the function may scan through the referenced
-buffer looking for the first zero byte.
+@item
+@samp{leafy} behaves like @samp{used} in a leaf function, and like
+@samp{all} in a nonleaf function. This makes for leaner zeroing in leaf
+functions, where the set of used registers is known, and that may be
+enough for some purposes of register zeroing.
+@end itemize
-In particular, when the analyzer is enabled (via @option{-fanalyzer}),
-if the pointer is non-null, it will simulate scanning for the first
-zero byte in the referenced buffer, and potentially emit
-@option{-Wanalyzer-use-of-uninitialized-value}
-or @option{-Wanalyzer-out-of-bounds} on improperly terminated buffers.
+In addition to these three basic choices, it is possible to modify
+@samp{used}, @samp{all}, and @samp{leafy} as follows:
-For example, given the following:
+@itemize @bullet
+@item
+Adding @samp{-gpr} restricts the zeroing to general-purpose registers.
-@smallexample
-char *example_1 (const char *p)
- __attribute__((null_terminated_string_arg (1)));
-@end smallexample
+@item
+Adding @samp{-arg} restricts the zeroing to registers that can sometimes
+be used to pass function arguments. This includes all argument registers
+defined by the platform's calling conversion, regardless of whether the
+function uses those registers for function arguments or not.
+@end itemize
-the analyzer will check that any non-null pointers passed to the function
-are validly terminated.
+The modifiers can be used individually or together. If they are used
+together, they must appear in the order above.
-If the parameter must be non-null, it is appropriate to use both this
-attribute and the attribute @code{nonnull}, such as in:
+The full list of @var{choice}s is therefore:
-@smallexample
-extern char *example_2 (const char *p)
- __attribute__((null_terminated_string_arg (1),
- nonnull (1)));
-@end smallexample
+@table @code
+@item skip
+doesn't zero any call-used register.
-See the @code{nonnull} attribute for more information and
-caveats.
+@item used
+only zeros call-used registers that are used in the function.
-If the pointer argument is also referred to by an @code{access} attribute on the
-function with @var{access-mode} either @code{read_only} or @code{read_write}
-and the latter attribute has the optional @var{size-index} argument
-referring to a size argument, this expresses the maximum size of the access.
-For example, given:
+@item used-gpr
+only zeros call-used general purpose registers that are used in the function.
-@smallexample
-extern char *example_fn (const char *p, size_t n)
- __attribute__((null_terminated_string_arg (1),
- access (read_only, 1, 2),
- nonnull (1)));
-@end smallexample
+@item used-arg
+only zeros call-used registers that are used in the function and pass arguments.
-the analyzer will require the first parameter to be non-null, and either
-be validly null-terminated, or validly readable up to the size specified by
-the second parameter.
+@item used-gpr-arg
+only zeros call-used general purpose registers that are used in the function
+and pass arguments.
-@cindex @code{optimize} function attribute
-@item optimize (@var{level}, @dots{})
-@item optimize (@var{string}, @dots{})
-The @code{optimize} attribute is used to specify that a function is to
-be compiled with different optimization options than specified on the
-command line. The optimize attribute arguments of a function behave
-as if appended to the command-line.
+@item all
+zeros all call-used registers.
-Valid arguments are constant non-negative integers and
-strings. Each numeric argument specifies an optimization @var{level}.
-Each @var{string} argument consists of one or more comma-separated
-substrings. Each substring that begins with the letter @code{O} refers
-to an optimization option such as @option{-O0} or @option{-Os}. Other
-substrings are taken as suffixes to the @code{-f} prefix jointly
-forming the name of an optimization option. @xref{Optimize Options}.
+@item all-gpr
+zeros all call-used general purpose registers.
-@samp{#pragma GCC optimize} can be used to set optimization options
-for more than one function. @xref{Function Specific Option Pragmas},
-for details about the pragma.
+@item all-arg
+zeros all call-used registers that pass arguments.
-Providing multiple strings as arguments separated by commas to specify
-multiple options is equivalent to separating the option suffixes with
-a comma (@samp{,}) within a single string. Spaces are not permitted
-within the strings.
-
-Not every optimization option that starts with the @var{-f} prefix
-specified by the attribute necessarily has an effect on the function.
-The @code{optimize} attribute should be used for debugging purposes only.
-It is not suitable in production code.
+@item all-gpr-arg
+zeros all call-used general purpose registers that pass
+arguments.
-@cindex @code{patchable_function_entry} function attribute
-@cindex extra NOP instructions at the function entry point
-@item patchable_function_entry
-In case the target's text segment can be made writable at run time by
-any means, padding the function entry with a number of NOPs can be
-used to provide a universal tool for instrumentation.
+@item leafy
+Same as @samp{used} in a leaf function, and same as @samp{all} in a
+nonleaf function.
-The @code{patchable_function_entry} function attribute can be used to
-change the number of NOPs to any desired value. The two-value syntax
-is the same as for the command-line switch
-@option{-fpatchable-function-entry=N,M}, generating @var{N} NOPs, with
-the function entry point before the @var{M}th NOP instruction.
-@var{M} defaults to 0 if omitted e.g.@: function entry point is before
-the first NOP.
+@item leafy-gpr
+Same as @samp{used-gpr} in a leaf function, and same as @samp{all-gpr}
+in a nonleaf function.
-If patchable function entries are enabled globally using the command-line
-option @option{-fpatchable-function-entry=N,M}, then you must disable
-instrumentation on all functions that are part of the instrumentation
-framework with the attribute @code{patchable_function_entry (0)}
-to prevent recursion.
+@item leafy-arg
+Same as @samp{used-arg} in a leaf function, and same as @samp{all-arg}
+in a nonleaf function.
-@cindex @code{pure} function attribute
-@cindex functions that have no side effects
-@item pure
+@item leafy-gpr-arg
+Same as @samp{used-gpr-arg} in a leaf function, and same as
+@samp{all-gpr-arg} in a nonleaf function.
-Calls to functions that have no observable effects on the state of
-the program other than to return a value may lend themselves to optimizations
-such as common subexpression elimination. Declaring such functions with
-the @code{pure} attribute allows GCC to avoid emitting some calls in repeated
-invocations of the function with the same argument values.
+@end table
-The @code{pure} attribute prohibits a function from modifying the state
-of the program that is observable by means other than inspecting
-the function's return value. However, functions declared with the @code{pure}
-attribute can safely read any non-volatile objects, and modify the value of
-objects in a way that does not affect their return value or the observable
-state of the program.
+Of this list, @samp{used-arg}, @samp{used-gpr-arg}, @samp{all-arg},
+@samp{all-gpr-arg}, @samp{leafy-arg}, and @samp{leafy-gpr-arg} are
+mainly used for ROP mitigation.
-For example,
+The default for the attribute is controlled by @option{-fzero-call-used-regs}.
+@end table
-@smallexample
-int hash (char *) __attribute__ ((pure));
-@end smallexample
+@c This is the end of the target-independent attribute table
-@noindent
-tells GCC that subsequent calls to the function @code{hash} with the same
-string can be replaced by the result of the first call provided the state
-of the program observable by @code{hash}, including the contents of the array
-itself, does not change in between. Even though @code{hash} takes a non-const
-pointer argument it must not modify the array it points to, or any other object
-whose value the rest of the program may depend on. However, the caller may
-safely change the contents of the array between successive calls to
-the function (doing so disables the optimization). The restriction also
-applies to member objects referenced by the @code{this} pointer in C++
-non-static member functions.
+@node AArch64 Function Attributes
+@subsection AArch64 Function Attributes
-Some common examples of pure functions are @code{strlen} or @code{memcmp}.
-Interesting non-pure functions are functions with infinite loops or those
-depending on volatile memory or other system resource, that may change between
-consecutive calls (such as the standard C @code{feof} function in
-a multithreading environment).
+The following target-specific function attributes are available for the
+AArch64 target. For the most part, these options mirror the behavior of
+similar command-line options (@pxref{AArch64 Options}), but on a
+per-function basis.
-The @code{pure} attribute imposes similar but looser restrictions on
-a function's definition than the @code{const} attribute: @code{pure}
-allows the function to read any non-volatile memory, even if it changes
-in between successive invocations of the function. Declaring the same
-function with both the @code{pure} and the @code{const} attribute is
-diagnosed. Because a pure function cannot have any observable side
-effects it does not make sense for such a function to return @code{void}.
-Declaring such a function is diagnosed.
+@table @code
+@cindex @code{general-regs-only} function attribute, AArch64
+@item general-regs-only
+Indicates that no floating-point or Advanced SIMD registers should be
+used when generating code for this function. If the function explicitly
+uses floating-point code, then the compiler gives an error. This is
+the same behavior as that of the command-line option
+@option{-mgeneral-regs-only}.
-@cindex @code{unsequenced} function type attribute
-@cindex functions that have no side effects
-@item unsequenced
+@cindex @code{fix-cortex-a53-835769} function attribute, AArch64
+@item fix-cortex-a53-835769
+Indicates that the workaround for the Cortex-A53 erratum 835769 should be
+applied to this function. To explicitly disable the workaround for this
+function specify the negated form: @code{no-fix-cortex-a53-835769}.
+This corresponds to the behavior of the command-line options
+@option{-mfix-cortex-a53-835769} and @option{-mno-fix-cortex-a53-835769}.
-This attribute is a GNU counterpart of the C23 @code{[[unsequenced]]}
-attribute, used to specify function pointers to effectless, idempotent,
-stateless and independent functions according to the C23 definition.
+@cindex @code{cmodel=} function attribute, AArch64
+@item cmodel=
+Indicates that code should be generated for a particular code model for
+this function. The behavior and permissible arguments are the same as
+for the command-line option @option{-mcmodel=}.
-Unlike the standard C23 attribute it can be also specified in attributes
-which appertain to function declarations and applies to the their function
-type even in that case.
+@cindex @code{strict-align} function attribute, AArch64
+@item strict-align
+@itemx no-strict-align
+@code{strict-align} indicates that the compiler should not assume that unaligned
+memory references are handled by the system. To allow the compiler to assume
+that aligned memory references are handled by the system, the inverse attribute
+@code{no-strict-align} can be specified. The behavior is same as for the
+command-line option @option{-mstrict-align} and @option{-mno-strict-align}.
-Unsequenced functions without pointer or reference arguments are similar
-to functions with the @code{const} attribute, except that @code{const}
-attribute also requires finiteness. So, both functions with @code{const}
-and with @code{unsequenced} attributes can be optimized by common
-subexpression elimination, but only functions with @code{const}
-attribute can be optimized by dead code elimination if their result is
-unused or is used only by dead code. Unsequenced functions without pointer
-or reference arguments with @code{void} return type are diagnosed because
-they can't store any results and don't have other observable side-effects
-either.
+@cindex @code{omit-leaf-frame-pointer} function attribute, AArch64
+@item omit-leaf-frame-pointer
+Indicates that the frame pointer should be omitted for a leaf function call.
+To keep the frame pointer, the inverse attribute
+@code{no-omit-leaf-frame-pointer} can be specified. These attributes have
+the same behavior as the command-line options @option{-momit-leaf-frame-pointer}
+and @option{-mno-omit-leaf-frame-pointer}.
-Unsequenced functions with pointer or reference arguments can inspect
-objects through the passed pointers or references or references to pointers
-or can store additional results through those pointers or references or
-references to pointers.
+@cindex @code{tls-dialect=} function attribute, AArch64
+@item tls-dialect=
+Specifies the TLS dialect to use for this function. The behavior and
+permissible arguments are the same as for the command-line option
+@option{-mtls-dialect=}.
-The @code{unsequenced} attribute imposes greater restrictions than
-the similar @code{reproducible} attribute and fewer restrictions than
-the @code{const} attribute, so during optimization @code{const} has
-precedence over @code{unsequenced} which has precedence over
-@code{reproducible}.
+@cindex @code{arch=} function attribute, AArch64
+@item arch=
+Specifies the architecture version and architectural extensions to use
+for this function. The behavior and permissible arguments are the same as
+for the @option{-march=} command-line option.
-@cindex @code{reproducible} function type attribute
-@cindex functions that have no side effects
-@item reproducible
+@cindex @code{tune=} function attribute, AArch64
+@item tune=
+Specifies the core for which to tune the performance of this function.
+The behavior and permissible arguments are the same as for the @option{-mtune=}
+command-line option.
-This attribute is a GNU counterpart of the C23 @code{[[reproducible]]}
-attribute, used to specify function pointers to effectless and idempotent
-functions according to the C23 definition.
+@cindex @code{cpu=} function attribute, AArch64
+@item cpu=
+Specifies the core for which to tune the performance of this function and also
+whose architectural features to use. The behavior and valid arguments are the
+same as for the @option{-mcpu=} command-line option.
-Unlike the standard C23 attribute it can be also specified in attributes
-which appertain to function declarations and applies to the their function
-type even in that case.
+@cindex @code{sign-return-address} function attribute, AArch64
+@item sign-return-address
+Select the function scope on which return address signing will be applied. The
+behavior and permissible arguments are the same as for the command-line option
+@option{-msign-return-address=}. The default value is @code{none}. This
+attribute is deprecated. The @code{branch-protection} attribute should
+be used instead.
-Reproducible functions without pointer or reference arguments or which do
-not modify objects referenced by those pointer/reference arguments are
-similar to functions with the @code{pure} attribute, except that
-@code{pure} attribute also requires finiteness. So, both functions with
-@code{pure} and with @code{reproducible} attributes can be optimized by common
-subexpression elimination if the global state or anything reachable through
-the pointer/reference arguments isn't modified, but only functions with
-@code{pure} attribute can be optimized by dead code elimination if their result is
-unused or is used only by dead code. Reproducible functions without pointer
-or reference arguments with @code{void} return type are diagnosed because
-they can't store any results and don't have other observable side-effects
-either.
+@cindex @code{branch-protection} function attribute, AArch64
+@item branch-protection
+Select the function scope on which branch protection will be applied. The
+behavior and permissible arguments are the same as for the command-line option
+@option{-mbranch-protection=}. The default value is @code{none}.
-Reproducible functions with pointer or reference arguments can store
-additional results through those pointers or references or references to
-pointers.
+@cindex @code{outline-atomics} function attribute, AArch64
+@item 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{retain} function attribute
-@item retain
-For ELF targets that support the GNU or FreeBSD OSABIs, this attribute
-will save the function from linker garbage collection. To support
-this behavior, functions that have not been placed in specific sections
-(e.g. by the @code{section} attribute, or the @code{-ffunction-sections}
-option), will be placed in new, unique sections.
+@cindex @code{indirect_return} function attribute, AArch64
+@item indirect_return
+The @code{indirect_return} attribute can be applied to a function type
+to indicate that the function may return via an indirect branch instead
+of via a normal return instruction. For example, this can be true of
+functions that implement manual context switching between user space
+threads, such as the POSIX @code{swapcontext} function. This attribute
+adds a @code{BTI J} instruction when BTI is enabled e.g. via
+@option{-mbranch-protection}.
-This additional functionality requires Binutils version 2.36 or later.
+@end table
-@cindex @code{returns_nonnull} function attribute
-@item returns_nonnull
-The @code{returns_nonnull} attribute specifies that the function
-return value should be a non-null pointer. For instance, the declaration:
+The above target attributes can be specified as follows:
@smallexample
-extern void *
-mymalloc (size_t len) __attribute__((returns_nonnull));
+__attribute__((target("@var{attr-string}")))
+int
+f (int a)
+@{
+ return a + 5;
+@}
@end smallexample
-@noindent
-lets the compiler optimize callers based on the knowledge
-that the return value will never be null.
+where @code{@var{attr-string}} is one of the attribute strings specified above.
-@cindex @code{returns_twice} function attribute
-@cindex functions that return more than once
-@item returns_twice
-The @code{returns_twice} attribute tells the compiler that a function may
-return more than one time. The compiler ensures that all registers
-are dead before calling such a function and emits a warning about
-the variables that may be clobbered after the second return from the
-function. Examples of such functions are @code{setjmp} and @code{vfork}.
-The @code{longjmp}-like counterpart of such function, if any, might need
-to be marked with the @code{noreturn} attribute.
-
-@cindex @code{section} function attribute
-@cindex functions in arbitrary sections
-@item section ("@var{section-name}")
-Normally, the compiler places the code it generates in the @code{text} section.
-Sometimes, however, you need additional sections, or you need certain
-particular functions to appear in special sections. The @code{section}
-attribute specifies that a function lives in a particular section.
-For example, the declaration:
+Additionally, the architectural extension string may be specified on its
+own. This can be used to turn on and off particular architectural extensions
+without having to specify a particular architecture version or core. Example:
@smallexample
-extern void foobar (void) __attribute__ ((section ("bar")));
+__attribute__((target("+crc+nocrypto")))
+int
+foo (int a)
+@{
+ return a + 5;
+@}
@end smallexample
-@noindent
-puts the function @code{foobar} in the @code{bar} section.
-
-Some file formats do not support arbitrary sections so the @code{section}
-attribute is not available on all platforms.
-If you need to map the entire contents of a module to a particular
-section, consider using the facilities of the linker instead.
-
-@cindex @code{sentinel} function attribute
-@item sentinel
-@itemx sentinel (@var{position})
-This function attribute indicates that an argument in a call to the function
-is expected to be an explicit @code{NULL}. The attribute is only valid on
-variadic functions. By default, the sentinel is expected to be the last
-argument of the function call. If the optional @var{position} argument
-is specified to the attribute, the sentinel must be located at
-@var{position} counting backwards from the end of the argument list.
+In this example @code{target("+crc+nocrypto")} enables the @code{crc}
+extension and disables the @code{crypto} extension for the function @code{foo}
+without modifying an existing @option{-march=} or @option{-mcpu} option.
+Multiple target function attributes can be specified by separating them with
+a comma. For example:
@smallexample
-__attribute__ ((sentinel))
-is equivalent to
-__attribute__ ((sentinel(0)))
+__attribute__((target("arch=armv8-a+crc+crypto,tune=cortex-a53")))
+int
+foo (int a)
+@{
+ return a + 5;
+@}
@end smallexample
-The attribute is automatically set with a position of 0 for the built-in
-functions @code{execl} and @code{execlp}. The built-in function
-@code{execle} has the attribute set with a position of 1.
+is valid and compiles function @code{foo} for ARMv8-A with @code{crc}
+and @code{crypto} extensions and tunes it for @code{cortex-a53}.
-A valid @code{NULL} in this context is defined as zero with any object
-pointer type. If your system defines the @code{NULL} macro with
-an integer type then you need to add an explicit cast. During
-installation GCC replaces the system @code{<stddef.h>} header with
-a copy that redefines NULL appropriately.
+@subsubsection 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:
-The warnings for missing or incorrect sentinels are enabled with
-@option{-Wformat}.
+In particular, a caller function can inline a callee function only if the
+architectural features available to the callee are a subset of the features
+available to the caller.
+For example: A function @code{foo} compiled with @option{-march=armv8-a+crc},
+or tagged with the equivalent @code{arch=armv8-a+crc} attribute,
+can inline a function @code{bar} compiled with @option{-march=armv8-a+nocrc}
+because the all the architectural features that function @code{bar} requires
+are available to function @code{foo}. Conversely, function @code{bar} cannot
+inline function @code{foo}.
-@cindex @code{simd} function attribute
-@item simd
-@itemx simd("@var{mask}")
-This attribute enables creation of one or more function versions that
-can process multiple arguments using SIMD instructions from a
-single invocation. Specifying this attribute allows compiler to
-assume that such versions are available at link time (provided
-in the same or another translation unit). Generated versions are
-target-dependent and described in the corresponding Vector ABI document. For
-x86_64 target this document can be found
-@w{@uref{https://sourceware.org/glibc/wiki/libmvec?action=AttachFile&do=view&target=VectorABI.txt,here}}.
+Additionally inlining a function compiled with @option{-mstrict-align} into a
+function compiled without @code{-mstrict-align} is not allowed.
+However, inlining a function compiled without @option{-mstrict-align} into a
+function compiled with @option{-mstrict-align} is allowed.
-The optional argument @var{mask} may have the value
-@code{notinbranch} or @code{inbranch},
-and instructs the compiler to generate non-masked or masked
-clones correspondingly. By default, all clones are generated.
+Note that CPU tuning options and attributes such as the @option{-mcpu=},
+@option{-mtune=} do not inhibit inlining unless the CPU specified by the
+@option{-mcpu=} option or the @code{cpu=} attribute conflicts with the
+architectural feature rules specified above.
-If the attribute is specified and @code{#pragma omp declare simd} is
-present on a declaration and the @option{-fopenmp} or @option{-fopenmp-simd}
-switch is specified, then the attribute is ignored.
+@node AMD GCN Function Attributes
+@subsection AMD GCN Function Attributes
-@cindex @code{stack_protect} function attribute
-@item stack_protect
-This attribute adds stack protection code to the function if
-flags @option{-fstack-protector}, @option{-fstack-protector-strong}
-or @option{-fstack-protector-explicit} are set.
+These function attributes are supported by the AMD GCN back end:
-@cindex @code{symver} function attribute
-@item symver ("@var{name2}@@@var{nodename}")
-On ELF targets this attribute creates a symbol version. The @var{name2} part
-of the parameter is the actual name of the symbol by which it will be
-externally referenced. The @code{nodename} portion should be the name of a
-node specified in the version script supplied to the linker when building a
-shared library. Versioned symbol must be defined and must be exported with
-default visibility.
+@table @code
+@cindex @code{amdgpu_hsa_kernel} function attribute, AMD GCN
+@item amdgpu_hsa_kernel
+This attribute indicates that the corresponding function should be compiled as
+a kernel function, that is an entry point that can be invoked from the host
+via the HSA runtime library. By default functions are only callable only from
+other GCN functions.
-@smallexample
-__attribute__ ((__symver__ ("foo@@VERS_1"))) int
-foo_v1 (void)
-@{
-@}
-@end smallexample
+This attribute is implicitly applied to any function named @code{main}, using
+default parameters.
-Will produce a @code{.symver foo_v1, foo@@VERS_1} directive in the assembler
-output.
+Kernel functions may return an integer value, which will be written to a
+conventional place within the HSA "kernargs" region.
-One can also define multiple version for a given symbol
-(starting from binutils 2.35).
+The attribute parameters configure what values are passed into the kernel
+function by the GPU drivers, via the initial register state. Some values are
+used by the compiler, and therefore forced on. Enabling other options may
+break assumptions in the compiler and/or run-time libraries.
-@smallexample
-__attribute__ ((__symver__ ("foo@@VERS_2"), __symver__ ("foo@@VERS_3")))
-int symver_foo_v1 (void)
-@{
-@}
-@end smallexample
+@table @code
+@item private_segment_buffer
+Set @code{enable_sgpr_private_segment_buffer} flag. Always on (required to
+locate the stack).
-This example creates a symbol name @code{symver_foo_v1}
-which will be version @code{VERS_2} and @code{VERS_3} of @code{foo}.
+@item dispatch_ptr
+Set @code{enable_sgpr_dispatch_ptr} flag. Always on (required to locate the
+launch dimensions).
-If you have an older release of binutils, then symbol alias needs to
-be used:
+@item queue_ptr
+Set @code{enable_sgpr_queue_ptr} flag. Always on (required to convert address
+spaces).
-@smallexample
-__attribute__ ((__symver__ ("foo@@VERS_2")))
-int foo_v1 (void)
-@{
- return 0;
-@}
+@item kernarg_segment_ptr
+Set @code{enable_sgpr_kernarg_segment_ptr} flag. Always on (required to
+locate the kernel arguments, "kernargs").
-__attribute__ ((__symver__ ("foo@@VERS_3")))
-__attribute__ ((alias ("foo_v1")))
-int symver_foo_v1 (void);
-@end smallexample
+@item dispatch_id
+Set @code{enable_sgpr_dispatch_id} flag.
-Finally if the parameter is @code{"@var{name2}@@@@@var{nodename}"} then in
-addition to creating a symbol version (as if
-@code{"@var{name2}@@@var{nodename}"} was used) the version will be also used
-to resolve @var{name2} by the linker.
+@item flat_scratch_init
+Set @code{enable_sgpr_flat_scratch_init} flag.
-@cindex @code{tainted_args} function attribute
-@item tainted_args
-The @code{tainted_args} attribute is used to specify that a function is called
-in a way that requires sanitization of its arguments, such as a system
-call in an operating system kernel. Such a function can be considered part
-of the ``attack surface'' of the program. The attribute can be used both
-on function declarations, and on field declarations containing function
-pointers. In the latter case, any function used as an initializer of
-such a callback field will be treated as being called with tainted
-arguments.
+@item private_segment_size
+Set @code{enable_sgpr_private_segment_size} flag.
-The analyzer will pay particular attention to such functions when
-@option{-fanalyzer} is supplied, potentially issuing warnings guarded by
-@option{-Wanalyzer-tainted-allocation-size},
-@option{-Wanalyzer-tainted-array-index},
-@option{-Wanalyzer-tainted-divisor},
-@option{-Wanalyzer-tainted-offset},
-and @option{-Wanalyzer-tainted-size}.
+@item grid_workgroup_count_X
+Set @code{enable_sgpr_grid_workgroup_count_x} flag. Always on (required to
+use OpenACC/OpenMP).
-@cindex @code{target} function attribute
-@item target (@var{string}, @dots{})
-Multiple target back ends implement the @code{target} attribute
-to specify that a function is to
-be compiled with different target options than specified on the
-command line. The original target command-line options are ignored.
-One or more strings can be provided as arguments.
-Each string consists of one or more comma-separated suffixes to
-the @code{-m} prefix jointly forming the name of a machine-dependent
-option. @xref{Submodel Options,,Machine-Dependent Options}.
+@item grid_workgroup_count_Y
+Set @code{enable_sgpr_grid_workgroup_count_y} flag.
-The @code{target} attribute can be used for instance to have a function
-compiled with a different ISA (instruction set architecture) than the
-default. @samp{#pragma GCC target} can be used to specify target-specific
-options for more than one function. @xref{Function Specific Option Pragmas},
-for details about the pragma.
+@item grid_workgroup_count_Z
+Set @code{enable_sgpr_grid_workgroup_count_z} flag.
-For instance, on an x86, you could declare one function with the
-@code{target("sse4.1,arch=core2")} attribute and another with
-@code{target("sse4a,arch=amdfam10")}. This is equivalent to
-compiling the first function with @option{-msse4.1} and
-@option{-march=core2} options, and the second function with
-@option{-msse4a} and @option{-march=amdfam10} options. It is up to you
-to make sure that a function is only invoked on a machine that
-supports the particular ISA it is compiled for (for example by using
-@code{cpuid} on x86 to determine what feature bits and architecture
-family are used).
+@item workgroup_id_X
+Set @code{enable_sgpr_workgroup_id_x} flag.
-@smallexample
-int core2_func (void) __attribute__ ((__target__ ("arch=core2")));
-int sse3_func (void) __attribute__ ((__target__ ("sse3")));
-@end smallexample
+@item workgroup_id_Y
+Set @code{enable_sgpr_workgroup_id_y} flag.
-Providing multiple strings as arguments separated by commas to specify
-multiple options is equivalent to separating the option suffixes with
-a comma (@samp{,}) within a single string. Spaces are not permitted
-within the strings.
-
-The options supported are specific to each target; refer to @ref{x86
-Function Attributes}, @ref{PowerPC Function Attributes},
-@ref{ARM Function Attributes}, @ref{AArch64 Function Attributes},
-and @ref{S/390 Function Attributes} for details.
-
-@cindex @code{target_clones} function attribute
-@item target_clones (@var{options})
-The @code{target_clones} attribute is used to specify that a function
-be cloned into multiple versions compiled with different target options
-than specified on the command line. The supported options and restrictions
-are the same as for @code{target} attribute.
-
-For instance, on an x86, you could compile a function with
-@code{target_clones("sse4.1,avx")}. GCC creates two function clones,
-one compiled with @option{-msse4.1} and another with @option{-mavx}.
+@item workgroup_id_Z
+Set @code{enable_sgpr_workgroup_id_z} flag.
-On a PowerPC, you can compile a function with
-@code{target_clones("cpu=power9,default")}. GCC will create two
-function clones, one compiled with @option{-mcpu=power9} and another
-with the default options. GCC must be configured to use GLIBC 2.23 or
-newer in order to use the @code{target_clones} attribute.
+@item workgroup_info
+Set @code{enable_sgpr_workgroup_info} flag.
-It also creates a resolver function (see
-the @code{ifunc} attribute above) that dynamically selects a clone
-suitable for current architecture. The resolver is created only if there
-is a usage of a function with @code{target_clones} attribute.
+@item private_segment_wave_offset
+Set @code{enable_sgpr_private_segment_wave_byte_offset} flag. Always on
+(required to locate the stack).
-Note that any subsequent call of a function without @code{target_clone}
-from a @code{target_clone} caller will not lead to copying
-(target clone) of the called function.
-If you want to enforce such behavior,
-we recommend declaring the calling function with the @code{flatten} attribute?
+@item work_item_id_X
+Set @code{enable_vgpr_workitem_id} parameter. Always on (can't be disabled).
-@cindex @code{unavailable} function attribute
-@item unavailable
-@itemx unavailable (@var{msg})
-The @code{unavailable} attribute results in an error if the function
-is used anywhere in the source file. This is useful when identifying
-functions that have been removed from a particular variation of an
-interface. Other than emitting an error rather than a warning, the
-@code{unavailable} attribute behaves in the same manner as
-@code{deprecated}.
+@item work_item_id_Y
+Set @code{enable_vgpr_workitem_id} parameter. Always on (required to enable
+vectorization.)
-The @code{unavailable} attribute can also be used for variables and
-types (@pxref{Variable Attributes}, @pxref{Type Attributes}.)
+@item work_item_id_Z
+Set @code{enable_vgpr_workitem_id} parameter. Always on (required to use
+OpenACC/OpenMP).
-@cindex @code{unused} function attribute
-@item unused
-This attribute, attached to a function, means that the function is meant
-to be possibly unused. GCC does not produce a warning for this
-function.
+@end table
+@end table
-@cindex @code{used} function attribute
-@item used
-This attribute, attached to a function, means that code must be emitted
-for the function even if it appears that the function is not referenced.
-This is useful, for example, when the function is referenced only in
-inline assembly.
+@node ARC Function Attributes
+@subsection ARC Function Attributes
-When applied to a member function of a C++ class template, the
-attribute also means that the function is instantiated if the
-class itself is instantiated.
+These function attributes are supported by the ARC back end:
-@cindex @code{visibility} function attribute
-@item visibility ("@var{visibility_type}")
-This attribute affects the linkage of the declaration to which it is attached.
-It can be applied to variables (@pxref{Common Variable Attributes}) and types
-(@pxref{Common Type Attributes}) as well as functions.
+@table @code
+@cindex @code{interrupt} function attribute, ARC
+@item interrupt
+Use this attribute to indicate
+that the specified function is an interrupt handler. The compiler generates
+function entry and exit sequences suitable for use in an interrupt handler
+when this attribute is present.
-There are four supported @var{visibility_type} values: default,
-hidden, protected or internal visibility.
+On the ARC, you must specify the kind of interrupt to be handled
+in a parameter to the interrupt attribute like this:
@smallexample
-void __attribute__ ((visibility ("protected")))
-f () @{ /* @r{Do something.} */; @}
-int i __attribute__ ((visibility ("hidden")));
+void f () __attribute__ ((interrupt ("ilink1")));
@end smallexample
-The possible values of @var{visibility_type} correspond to the
-visibility settings in the ELF gABI.
-
-@table @code
-@c keep this list of visibilities in alphabetical order.
-
-@item default
-Default visibility is the normal case for the object file format.
-This value is available for the visibility attribute to override other
-options that may change the assumed visibility of entities.
+Permissible values for this parameter are: @w{@code{ilink1}} and
+@w{@code{ilink2}} for ARCv1 architecture, and @w{@code{ilink}} and
+@w{@code{firq}} for ARCv2 architecture.
-On ELF, default visibility means that the declaration is visible to other
-modules and, in shared libraries, means that the declared entity may be
-overridden.
+@cindex @code{long_call} function attribute, ARC
+@cindex @code{medium_call} function attribute, ARC
+@cindex @code{short_call} function attribute, ARC
+@cindex indirect calls, ARC
+@item long_call
+@itemx medium_call
+@itemx short_call
+These attributes specify how a particular function is called.
+These attributes override the
+@option{-mlong-calls} and @option{-mmedium-calls} (@pxref{ARC Options})
+command-line switches and @code{#pragma long_calls} settings.
-On Darwin, default visibility means that the declaration is visible to
-other modules.
+For ARC, a function marked with the @code{long_call} attribute is
+always called using register-indirect jump-and-link instructions,
+thereby enabling the called function to be placed anywhere within the
+32-bit address space. A function marked with the @code{medium_call}
+attribute will always be close enough to be called with an unconditional
+branch-and-link instruction, which has a 25-bit offset from
+the call site. A function marked with the @code{short_call}
+attribute will always be close enough to be called with a conditional
+branch-and-link instruction, which has a 21-bit offset from
+the call site.
-Default visibility corresponds to ``external linkage'' in the language.
+@cindex @code{jli_always} function attribute, ARC
+@item jli_always
+Forces a particular function to be called using @code{jli}
+instruction. The @code{jli} instruction makes use of a table stored
+into @code{.jlitab} section, which holds the location of the functions
+which are addressed using this instruction.
-@item hidden
-Hidden visibility indicates that the entity declared has a new
-form of linkage, which we call ``hidden linkage''. Two
-declarations of an object with hidden linkage refer to the same object
-if they are in the same shared object.
+@cindex @code{jli_fixed} function attribute, ARC
+@item jli_fixed
+Identical like the above one, but the location of the function in the
+@code{jli} table is known and given as an attribute parameter.
-@item internal
-Internal visibility is like hidden visibility, but with additional
-processor specific semantics. Unless otherwise specified by the
-psABI, GCC defines internal visibility to mean that a function is
-@emph{never} called from another module. Compare this with hidden
-functions which, while they cannot be referenced directly by other
-modules, can be referenced indirectly via function pointers. By
-indicating that a function cannot be called from outside the module,
-GCC may for instance omit the load of a PIC register since it is known
-that the calling function loaded the correct value.
+@cindex @code{secure_call} function attribute, ARC
+@item secure_call
+This attribute allows one to mark secure-code functions that are
+callable from normal mode. The location of the secure call function
+into the @code{sjli} table needs to be passed as argument.
-@item protected
-Protected visibility is like default visibility except that it
-indicates that references within the defining module bind to the
-definition in that module. That is, the declared entity cannot be
-overridden by another module.
+@cindex @code{naked} function attribute, ARC
+@item naked
+This attribute allows the compiler to construct the requisite function
+declaration, while allowing the body of the function to be assembly
+code. The specified function will not have prologue/epilogue
+sequences generated by the compiler. Only basic @code{asm} statements
+can safely be included in naked functions (@pxref{Basic Asm}). While
+using extended @code{asm} or a mixture of basic @code{asm} and C code
+may appear to work, they cannot be depended upon to work reliably and
+are not supported.
@end table
-All visibilities are supported on many, but not all, ELF targets
-(supported when the assembler supports the @samp{.visibility}
-pseudo-op). Default visibility is supported everywhere. Hidden
-visibility is supported on Darwin targets.
+@node ARM Function Attributes
+@subsection ARM Function Attributes
-The visibility attribute should be applied only to declarations that
-would otherwise have external linkage. The attribute should be applied
-consistently, so that the same entity should not be declared with
-different settings of the attribute.
+These function attributes are supported for ARM targets:
-In C++, the visibility attribute applies to types as well as functions
-and objects, because in C++ types have linkage. A class must not have
-greater visibility than its non-static data member types and bases,
-and class members default to the visibility of their class. Also, a
-declaration without explicit visibility is limited to the visibility
-of its type.
+@table @code
-In C++, you can mark member functions and static member variables of a
-class with the visibility attribute. This is useful if you know a
-particular method or static member variable should only be used from
-one shared object; then you can mark it hidden while the rest of the
-class has default visibility. Care must be taken to avoid breaking
-the One Definition Rule; for example, it is usually not useful to mark
-an inline method as hidden without marking the whole class as hidden.
+@cindex @code{general-regs-only} function attribute, ARM
+@item general-regs-only
+Indicates that no floating-point or Advanced SIMD registers should be
+used when generating code for this function. If the function explicitly
+uses floating-point code, then the compiler gives an error. This is
+the same behavior as that of the command-line option
+@option{-mgeneral-regs-only}.
-A C++ namespace declaration can also have the visibility attribute.
+@cindex @code{interrupt} function attribute, ARM
+@item interrupt
+Use this attribute to indicate
+that the specified function is an interrupt handler. The compiler generates
+function entry and exit sequences suitable for use in an interrupt handler
+when this attribute is present.
+
+You can specify the kind of interrupt to be handled by
+adding an optional parameter to the interrupt attribute like this:
@smallexample
-namespace nspace1 __attribute__ ((visibility ("protected")))
-@{ /* @r{Do something.} */; @}
+void f () __attribute__ ((interrupt ("IRQ")));
@end smallexample
-This attribute applies only to the particular namespace body, not to
-other definitions of the same namespace; it is equivalent to using
-@samp{#pragma GCC visibility} before and after the namespace
-definition (@pxref{Visibility Pragmas}).
-
-In C++, if a template argument has limited visibility, this
-restriction is implicitly propagated to the template instantiation.
-Otherwise, template instantiations and specializations default to the
-visibility of their template.
+@noindent
+Permissible values for this parameter are: @code{IRQ}, @code{FIQ},
+@code{SWI}, @code{ABORT} and @code{UNDEF}.
-If both the template and enclosing class have explicit visibility, the
-visibility from the template is used.
+On ARMv7-M the interrupt type is ignored, and the attribute means the function
+may be called with a word-aligned stack pointer.
-@cindex @code{warn_unused_result} function attribute
-@item warn_unused_result
-The @code{warn_unused_result} attribute causes a warning to be emitted
-if a caller of the function with this attribute does not use its
-return value. This is useful for functions where not checking
-the result is either a security problem or always a bug, such as
-@code{realloc}.
+@cindex @code{isr} function attribute, ARM
+@item isr
+Use this attribute on ARM to write Interrupt Service Routines. This is an
+alias to the @code{interrupt} attribute above.
-@smallexample
-int fn () __attribute__ ((warn_unused_result));
-int foo ()
-@{
- if (fn () < 0) return -1;
- fn ();
- return 0;
-@}
-@end smallexample
+@cindex @code{long_call} function attribute, ARM
+@cindex @code{short_call} function attribute, ARM
+@cindex indirect calls, ARM
+@item long_call
+@itemx short_call
+These attributes specify how a particular function is called.
+These attributes override the
+@option{-mlong-calls} (@pxref{ARM Options})
+command-line switch and @code{#pragma long_calls} settings. For ARM, the
+@code{long_call} attribute indicates that the function might be far
+away from the call site and require a different (more expensive)
+calling sequence. The @code{short_call} attribute always places
+the offset to the function from the call site into the @samp{BL}
+instruction directly.
-@noindent
-results in warning on line 5.
+@cindex @code{naked} function attribute, ARM
+@item naked
+This attribute allows the compiler to construct the
+requisite function declaration, while allowing the body of the
+function to be assembly code. The specified function will not have
+prologue/epilogue sequences generated by the compiler. Only basic
+@code{asm} statements can safely be included in naked functions
+(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
+basic @code{asm} and C code may appear to work, they cannot be
+depended upon to work reliably and are not supported.
-@cindex @code{weak} function attribute
-@item weak
-The @code{weak} attribute causes a declaration of an external symbol
-to be emitted as a weak symbol rather than a global. This is primarily
-useful in defining library functions that can be overridden in user code,
-though it can also be used with non-function declarations. The overriding
-symbol must have the same type as the weak symbol. In addition, if it
-designates a variable it must also have the same size and alignment as
-the weak symbol. Weak symbols are supported for ELF targets, and also
-for a.out targets when using the GNU assembler and linker.
+@cindex @code{pcs} function attribute, ARM
+@item pcs
-@cindex @code{weakref} function attribute
-@item weakref
-@itemx weakref ("@var{target}")
-The @code{weakref} attribute marks a declaration as a weak reference.
-Without arguments, it should be accompanied by an @code{alias} attribute
-naming the target symbol. Alternatively, @var{target} may be given as
-an argument to @code{weakref} itself, naming the target definition of
-the alias. The @var{target} must have the same type as the declaration.
-In addition, if it designates a variable it must also have the same size
-and alignment as the declaration. In either form of the declaration
-@code{weakref} implicitly marks the declared symbol as @code{weak}. Without
-a @var{target} given as an argument to @code{weakref} or to @code{alias},
-@code{weakref} is equivalent to @code{weak} (in that case the declaration
-may be @code{extern}).
+The @code{pcs} attribute can be used to control the calling convention
+used for a function on ARM. The attribute takes an argument that specifies
+the calling convention to use.
-@smallexample
-/* Given the declaration: */
-extern int y (void);
+When compiling using the AAPCS ABI (or a variant of it) then valid
+values for the argument are @code{"aapcs"} and @code{"aapcs-vfp"}. In
+order to use a variant other than @code{"aapcs"} then the compiler must
+be permitted to use the appropriate co-processor registers (i.e., the
+VFP registers must be available in order to use @code{"aapcs-vfp"}).
+For example,
-/* the following... */
-static int x (void) __attribute__ ((weakref ("y")));
+@smallexample
+/* Argument passed in r0, and result returned in r0+r1. */
+double f2d (float) __attribute__((pcs("aapcs")));
+@end smallexample
-/* is equivalent to... */
-static int x (void) __attribute__ ((weakref, alias ("y")));
+Variadic functions always use the @code{"aapcs"} calling convention and
+the compiler rejects attempts to specify an alternative.
-/* or, alternatively, to... */
-static int x (void) __attribute__ ((weakref));
-static int x (void) __attribute__ ((alias ("y")));
-@end smallexample
+@cindex @code{target} function attribute
+@item target (@var{options})
+As discussed in @ref{Common Function Attributes}, this attribute
+allows specification of target-specific compilation options.
-A weak reference is an alias that does not by itself require a
-definition to be given for the target symbol. If the target symbol is
-only referenced through weak references, then it becomes a @code{weak}
-undefined symbol. If it is directly referenced, however, then such
-strong references prevail, and a definition is required for the
-symbol, not necessarily in the same translation unit.
+On ARM, the following options are allowed:
-The effect is equivalent to moving all references to the alias to a
-separate translation unit, renaming the alias to the aliased symbol,
-declaring it as weak, compiling the two separate translation units and
-performing a link with relocatable output (i.e.@: @code{ld -r}) on them.
+@table @samp
+@cindex @code{target("thumb")} function attribute, ARM
+@item thumb
+Force code generation in the Thumb (T16/T32) ISA, depending on the
+architecture level.
-A declaration to which @code{weakref} is attached and that is associated
-with a named @code{target} must be @code{static}.
+@cindex @code{target("arm")} function attribute, ARM
+@item arm
+Force code generation in the ARM (A32) ISA.
-@cindex @code{zero_call_used_regs} function attribute
-@item zero_call_used_regs ("@var{choice}")
+Functions from different modes can be inlined in the caller's mode.
-The @code{zero_call_used_regs} attribute causes the compiler to zero
-a subset of all call-used registers@footnote{A ``call-used'' register
-is a register whose contents can be changed by a function call;
-therefore, a caller cannot assume that the register has the same contents
-on return from the function as it had before calling the function. Such
-registers are also called ``call-clobbered'', ``caller-saved'', or
-``volatile''.} at function return.
-This is used to increase program security by either mitigating
-Return-Oriented Programming (ROP) attacks or preventing information leakage
-through registers.
+@cindex @code{target("fpu=")} function attribute, ARM
+@item fpu=
+Specifies the fpu for which to tune the performance of this function.
+The behavior and permissible arguments are the same as for the @option{-mfpu=}
+command-line option.
-In order to satisfy users with different security needs and control the
-run-time overhead at the same time, the @var{choice} parameter provides a
-flexible way to choose the subset of the call-used registers to be zeroed.
-The four basic values of @var{choice} are:
+@cindex @code{arch=} function attribute, ARM
+@item arch=
+Specifies the architecture version and architectural extensions to use
+for this function. The behavior and permissible arguments are the same as
+for the @option{-march=} command-line option.
-@itemize @bullet
-@item
-@samp{skip} doesn't zero any call-used registers.
+The above target attributes can be specified as follows:
-@item
-@samp{used} only zeros call-used registers that are used in the function.
-A ``used'' register is one whose content has been set or referenced in
-the function.
+@smallexample
+__attribute__((target("arch=armv8-a+crc")))
+int
+f (int a)
+@{
+ return a + 5;
+@}
+@end smallexample
-@item
-@samp{all} zeros all call-used registers.
+Additionally, the architectural extension string may be specified on its
+own. This can be used to turn on and off particular architectural extensions
+without having to specify a particular architecture version or core. Example:
-@item
-@samp{leafy} behaves like @samp{used} in a leaf function, and like
-@samp{all} in a nonleaf function. This makes for leaner zeroing in leaf
-functions, where the set of used registers is known, and that may be
-enough for some purposes of register zeroing.
-@end itemize
+@smallexample
+__attribute__((target("+crc+nocrypto")))
+int
+foo (int a)
+@{
+ return a + 5;
+@}
+@end smallexample
-In addition to these three basic choices, it is possible to modify
-@samp{used}, @samp{all}, and @samp{leafy} as follows:
+In this example @code{target("+crc+nocrypto")} enables the @code{crc}
+extension and disables the @code{crypto} extension for the function @code{foo}
+without modifying an existing @option{-march=} or @option{-mcpu} option.
-@itemize @bullet
-@item
-Adding @samp{-gpr} restricts the zeroing to general-purpose registers.
+@end table
-@item
-Adding @samp{-arg} restricts the zeroing to registers that can sometimes
-be used to pass function arguments. This includes all argument registers
-defined by the platform's calling conversion, regardless of whether the
-function uses those registers for function arguments or not.
-@end itemize
+@end table
-The modifiers can be used individually or together. If they are used
-together, they must appear in the order above.
+@node AVR Function Attributes
+@subsection AVR Function Attributes
-The full list of @var{choice}s is therefore:
+These function attributes are supported by the AVR back end:
@table @code
-@item skip
-doesn't zero any call-used register.
+@cindex @code{signal} function attribute, AVR
+@cindex @code{interrupt} function attribute, AVR
+@item signal
+@itemx interrupt
+The function is an interrupt service routine (ISR). The compiler generates
+function entry and exit sequences suitable for use in an interrupt handler
+when one of the attributes is present.
-@item used
-only zeros call-used registers that are used in the function.
+The AVR hardware globally disables interrupts when an interrupt is executed.
-@item used-gpr
-only zeros call-used general purpose registers that are used in the function.
+@itemize @bullet
+@item ISRs with the @code{signal} attribute do not re-enable interrupts.
+It is save to enable interrupts in a @code{signal} handler.
+This ``save'' only applies to the code
+generated by the compiler and not to the IRQ layout of the
+application which is responsibility of the application.
-@item used-arg
-only zeros call-used registers that are used in the function and pass arguments.
+@item ISRs with the @code{interrupt} attribute re-enable interrupts.
+The first instruction of the routine is a @code{SEI} instruction to
+globally enable interrupts.
+@end itemize
-@item used-gpr-arg
-only zeros call-used general purpose registers that are used in the function
-and pass arguments.
+The recommended way to use these attributes is by means of the
+@code{ISR} macro provided by @code{avr/interrupt.h} from
+@w{@uref{https://avrdudes.github.io/avr-libc/avr-libc-user-manual/group__avr__interrupts.html,,AVR-LibC}}:
+@example
+#include <avr/interrupt.h>
-@item all
-zeros all call-used registers.
+ISR (INT0_vect) // Uses the "signal" attribute.
+@{
+ // Code
+@}
-@item all-gpr
-zeros all call-used general purpose registers.
+ISR (ADC_vect, ISR_NOBLOCK) // Uses the "interrupt" attribute.
+@{
+ // Code
+@}
+@end example
-@item all-arg
-zeros all call-used registers that pass arguments.
+When both @code{signal} and @code{interrupt} are specified for the same
+function, then @code{signal} is silently ignored.
-@item all-gpr-arg
-zeros all call-used general purpose registers that pass
-arguments.
+@cindex @code{signal(@var{num})} function attribute, AVR
+@cindex @code{interrupt(@var{num})} function attribute, AVR
+@item signal(@var{num})
+@itemx interrupt(@var{num})
-@item leafy
-Same as @samp{used} in a leaf function, and same as @samp{all} in a
-nonleaf function.
+Similar to the @code{signal} resp. @code{interrupt} attribute without
+argument, but the IRQ number is supplied as an argument @var{num} to
+the attribute, rather than providing the ISR name itself as the function name:
-@item leafy-gpr
-Same as @samp{used-gpr} in a leaf function, and same as @samp{all-gpr}
-in a nonleaf function.
-
-@item leafy-arg
-Same as @samp{used-arg} in a leaf function, and same as @samp{all-arg}
-in a nonleaf function.
-
-@item leafy-gpr-arg
-Same as @samp{used-gpr-arg} in a leaf function, and same as
-@samp{all-gpr-arg} in a nonleaf function.
-
-@end table
+@example
+__attribute__((signal(1)))
+static void my_handler (void)
+@{
+ // Code for __vector_1
+@}
+@end example
-Of this list, @samp{used-arg}, @samp{used-gpr-arg}, @samp{all-arg},
-@samp{all-gpr-arg}, @samp{leafy-arg}, and @samp{leafy-gpr-arg} are
-mainly used for ROP mitigation.
+Notice that the handler function needs not to be externally visible.
+The recommended way to use these attributes is by means of the
+@code{ISR_N} macro provided by @code{avr/interrupt.h} from
+@w{@uref{https://avrdudes.github.io/avr-libc/avr-libc-user-manual/group__avr__interrupts.html,,AVR-LibC}}:
-The default for the attribute is controlled by @option{-fzero-call-used-regs}.
-@end table
+@example
+#include <avr/interrupt.h>
-@c This is the end of the target-independent attribute table
+ISR_N (PCINT0_vect_num)
+static void my_pcint0_handler (void)
+@{
+ // Code
+@}
-@node AArch64 Function Attributes
-@subsection AArch64 Function Attributes
+ISR_N (ADC_vect_num, ISR_NOBLOCK)
+static void my_adc_handler (void)
+@{
+ // Code
+@}
+@end example
-The following target-specific function attributes are available for the
-AArch64 target. For the most part, these options mirror the behavior of
-similar command-line options (@pxref{AArch64 Options}), but on a
-per-function basis.
+@code{ISR_N} can be specified more than once, in which case several
+interrupt vectors are pointing to the same handler function. This
+is similar to the @code{ISR_ALIASOF} macro provided by AVR-LibC, but
+without the overhead introduced by @code{ISR_ALIASOF}.
-@table @code
-@cindex @code{general-regs-only} function attribute, AArch64
-@item general-regs-only
-Indicates that no floating-point or Advanced SIMD registers should be
-used when generating code for this function. If the function explicitly
-uses floating-point code, then the compiler gives an error. This is
-the same behavior as that of the command-line option
-@option{-mgeneral-regs-only}.
-@cindex @code{fix-cortex-a53-835769} function attribute, AArch64
-@item fix-cortex-a53-835769
-Indicates that the workaround for the Cortex-A53 erratum 835769 should be
-applied to this function. To explicitly disable the workaround for this
-function specify the negated form: @code{no-fix-cortex-a53-835769}.
-This corresponds to the behavior of the command-line options
-@option{-mfix-cortex-a53-835769} and @option{-mno-fix-cortex-a53-835769}.
+@cindex @code{noblock} function attribute, AVR
+@item noblock
-@cindex @code{cmodel=} function attribute, AArch64
-@item cmodel=
-Indicates that code should be generated for a particular code model for
-this function. The behavior and permissible arguments are the same as
-for the command-line option @option{-mcmodel=}.
+This attribute can be used together with the @code{signal} attribute
+to indicate that an interrupt service routine should start with a @code{SEI}
+instruction to globally re-enable interrupts. Using attributes @code{signal}
+and @code{noblock} together has the same effect like using the @code{interrupt}
+attribute. Using the @code{noblock} attribute without @code{signal} has no
+effect.
-@cindex @code{strict-align} function attribute, AArch64
-@item strict-align
-@itemx no-strict-align
-@code{strict-align} indicates that the compiler should not assume that unaligned
-memory references are handled by the system. To allow the compiler to assume
-that aligned memory references are handled by the system, the inverse attribute
-@code{no-strict-align} can be specified. The behavior is same as for the
-command-line option @option{-mstrict-align} and @option{-mno-strict-align}.
+@cindex @code{naked} function attribute, AVR
+@item naked
+This attribute allows the compiler to construct the
+requisite function declaration, while allowing the body of the
+function to be assembly code. The specified function will not have
+prologue/epilogue sequences generated by the compiler. Only basic
+@code{asm} statements can safely be included in naked functions
+(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
+basic @code{asm} and C code may appear to work, they cannot be
+depended upon to work reliably and are not supported.
-@cindex @code{omit-leaf-frame-pointer} function attribute, AArch64
-@item omit-leaf-frame-pointer
-Indicates that the frame pointer should be omitted for a leaf function call.
-To keep the frame pointer, the inverse attribute
-@code{no-omit-leaf-frame-pointer} can be specified. These attributes have
-the same behavior as the command-line options @option{-momit-leaf-frame-pointer}
-and @option{-mno-omit-leaf-frame-pointer}.
+@cindex @code{no_gccisr} function attribute, AVR
+@item no_gccisr
+Do not use the @code{__gcc_isr}
+@uref{https://sourceware.org/binutils/docs/as/AVR-Pseudo-Instructions.html,pseudo instruction}
+in a function with
+the @code{interrupt} or @code{signal} attribute aka. interrupt
+service routine (ISR).
+Use this attribute if the preamble of the ISR prologue should always read
+@example
+push __zero_reg__
+push __tmp_reg__
+in __tmp_reg__, __SREG__
+push __tmp_reg__
+clr __zero_reg__
+@end example
+and accordingly for the postamble of the epilogue --- no matter whether
+the mentioned registers are actually used in the ISR or not.
+Situations where you might want to use this attribute include:
+@itemize @bullet
+@item
+Code that (effectively) clobbers bits of @code{SREG} other than the
+@code{I}-flag by writing to the memory location of @code{SREG}.
+@item
+Code that uses inline assembler to jump to a different function which
+expects (parts of) the prologue code as outlined above to be present.
+@end itemize
+To disable @code{__gcc_isr} generation for the whole compilation unit,
+there is option @option{-mno-gas-isr-prologues}, @pxref{AVR Options}.
-@cindex @code{tls-dialect=} function attribute, AArch64
-@item tls-dialect=
-Specifies the TLS dialect to use for this function. The behavior and
-permissible arguments are the same as for the command-line option
-@option{-mtls-dialect=}.
+@cindex @code{OS_main} function attribute, AVR
+@cindex @code{OS_task} function attribute, AVR
+@item OS_main
+@itemx OS_task
+On AVR, functions with the @code{OS_main} or @code{OS_task} attribute
+do not save/restore any call-saved register in their prologue/epilogue.
-@cindex @code{arch=} function attribute, AArch64
-@item arch=
-Specifies the architecture version and architectural extensions to use
-for this function. The behavior and permissible arguments are the same as
-for the @option{-march=} command-line option.
+The @code{OS_main} attribute can be used when there @emph{is
+guarantee} that interrupts are disabled at the time when the function
+is entered. This saves resources when the stack pointer has to be
+changed to set up a frame for local variables.
-@cindex @code{tune=} function attribute, AArch64
-@item tune=
-Specifies the core for which to tune the performance of this function.
-The behavior and permissible arguments are the same as for the @option{-mtune=}
-command-line option.
+The @code{OS_task} attribute can be used when there is @emph{no
+guarantee} that interrupts are disabled at that time when the function
+is entered like for, e@.g@. task functions in a multi-threading operating
+system. In that case, changing the stack pointer register is
+guarded by save/clear/restore of the global interrupt enable flag.
-@cindex @code{cpu=} function attribute, AArch64
-@item cpu=
-Specifies the core for which to tune the performance of this function and also
-whose architectural features to use. The behavior and valid arguments are the
-same as for the @option{-mcpu=} command-line option.
+The differences to the @code{naked} function attribute are:
+@itemize @bullet
+@item @code{naked} functions do not have a return instruction whereas
+@code{OS_main} and @code{OS_task} functions have a @code{RET} or
+@code{RETI} return instruction.
+@item @code{naked} functions do not set up a frame for local variables
+or a frame pointer whereas @code{OS_main} and @code{OS_task} do this
+as needed.
+@end itemize
-@cindex @code{sign-return-address} function attribute, AArch64
-@item sign-return-address
-Select the function scope on which return address signing will be applied. The
-behavior and permissible arguments are the same as for the command-line option
-@option{-msign-return-address=}. The default value is @code{none}. This
-attribute is deprecated. The @code{branch-protection} attribute should
-be used instead.
+@end table
-@cindex @code{branch-protection} function attribute, AArch64
-@item branch-protection
-Select the function scope on which branch protection will be applied. The
-behavior and permissible arguments are the same as for the command-line option
-@option{-mbranch-protection=}. The default value is @code{none}.
+@node Blackfin Function Attributes
+@subsection Blackfin Function Attributes
-@cindex @code{outline-atomics} function attribute, AArch64
-@item 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}.
+These function attributes are supported by the Blackfin back end:
-@cindex @code{indirect_return} function attribute, AArch64
-@item indirect_return
-The @code{indirect_return} attribute can be applied to a function type
-to indicate that the function may return via an indirect branch instead
-of via a normal return instruction. For example, this can be true of
-functions that implement manual context switching between user space
-threads, such as the POSIX @code{swapcontext} function. This attribute
-adds a @code{BTI J} instruction when BTI is enabled e.g. via
-@option{-mbranch-protection}.
+@table @code
-@end table
+@cindex @code{exception_handler} function attribute
+@cindex exception handler functions, Blackfin
+@item exception_handler
+Use this attribute on the Blackfin to indicate that the specified function
+is an exception handler. The compiler generates function entry and
+exit sequences suitable for use in an exception handler when this
+attribute is present.
-The above target attributes can be specified as follows:
+@cindex @code{interrupt_handler} function attribute, Blackfin
+@item interrupt_handler
+Use this attribute to
+indicate that the specified function is an interrupt handler. The compiler
+generates function entry and exit sequences suitable for use in an
+interrupt handler when this attribute is present.
-@smallexample
-__attribute__((target("@var{attr-string}")))
-int
-f (int a)
-@{
- return a + 5;
-@}
-@end smallexample
+@cindex @code{kspisusp} function attribute, Blackfin
+@cindex User stack pointer in interrupts on the Blackfin
+@item kspisusp
+When used together with @code{interrupt_handler}, @code{exception_handler}
+or @code{nmi_handler}, code is generated to load the stack pointer
+from the USP register in the function prologue.
-where @code{@var{attr-string}} is one of the attribute strings specified above.
+@cindex @code{l1_text} function attribute, Blackfin
+@item l1_text
+This attribute specifies a function to be placed into L1 Instruction
+SRAM@. The function is put into a specific section named @code{.l1.text}.
+With @option{-mfdpic}, function calls with a such function as the callee
+or caller uses inlined PLT.
-Additionally, the architectural extension string may be specified on its
-own. This can be used to turn on and off particular architectural extensions
-without having to specify a particular architecture version or core. Example:
+@cindex @code{l2} function attribute, Blackfin
+@item l2
+This attribute specifies a function to be placed into L2
+SRAM. The function is put into a specific section named
+@code{.l2.text}. With @option{-mfdpic}, callers of such functions use
+an inlined PLT.
-@smallexample
-__attribute__((target("+crc+nocrypto")))
-int
-foo (int a)
-@{
- return a + 5;
-@}
-@end smallexample
-
-In this example @code{target("+crc+nocrypto")} enables the @code{crc}
-extension and disables the @code{crypto} extension for the function @code{foo}
-without modifying an existing @option{-march=} or @option{-mcpu} option.
-
-Multiple target function attributes can be specified by separating them with
-a comma. For example:
-@smallexample
-__attribute__((target("arch=armv8-a+crc+crypto,tune=cortex-a53")))
-int
-foo (int a)
-@{
- return a + 5;
-@}
-@end smallexample
-
-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
-Specifying target attributes on individual functions or performing link-time
-optimization across translation units compiled with different target options
-can affect function inlining rules:
-
-In particular, a caller function can inline a callee function only if the
-architectural features available to the callee are a subset of the features
-available to the caller.
-For example: A function @code{foo} compiled with @option{-march=armv8-a+crc},
-or tagged with the equivalent @code{arch=armv8-a+crc} attribute,
-can inline a function @code{bar} compiled with @option{-march=armv8-a+nocrc}
-because the all the architectural features that function @code{bar} requires
-are available to function @code{foo}. Conversely, function @code{bar} cannot
-inline function @code{foo}.
-
-Additionally inlining a function compiled with @option{-mstrict-align} into a
-function compiled without @code{-mstrict-align} is not allowed.
-However, inlining a function compiled without @option{-mstrict-align} into a
-function compiled with @option{-mstrict-align} is allowed.
-
-Note that CPU tuning options and attributes such as the @option{-mcpu=},
-@option{-mtune=} do not inhibit inlining unless the CPU specified by the
-@option{-mcpu=} option or the @code{cpu=} attribute conflicts with the
-architectural feature rules specified above.
-
-@node AMD GCN Function Attributes
-@subsection AMD GCN Function Attributes
+@cindex indirect calls, Blackfin
+@cindex @code{longcall} function attribute, Blackfin
+@cindex @code{shortcall} function attribute, Blackfin
+@item longcall
+@itemx shortcall
+The @code{longcall} attribute
+indicates that the function might be far away from the call site and
+require a different (more expensive) calling sequence. The
+@code{shortcall} attribute indicates that the function is always close
+enough for the shorter calling sequence to be used. These attributes
+override the @option{-mlongcall} switch.
-These function attributes are supported by the AMD GCN back end:
+@cindex @code{nesting} function attribute, Blackfin
+@cindex Allow nesting in an interrupt handler on the Blackfin processor
+@item nesting
+Use this attribute together with @code{interrupt_handler},
+@code{exception_handler} or @code{nmi_handler} to indicate that the function
+entry code should enable nested interrupts or exceptions.
-@table @code
-@cindex @code{amdgpu_hsa_kernel} function attribute, AMD GCN
-@item amdgpu_hsa_kernel
-This attribute indicates that the corresponding function should be compiled as
-a kernel function, that is an entry point that can be invoked from the host
-via the HSA runtime library. By default functions are only callable only from
-other GCN functions.
+@cindex @code{nmi_handler} function attribute, Blackfin
+@cindex NMI handler functions on the Blackfin processor
+@item nmi_handler
+Use this attribute on the Blackfin to indicate that the specified function
+is an NMI handler. The compiler generates function entry and
+exit sequences suitable for use in an NMI handler when this
+attribute is present.
-This attribute is implicitly applied to any function named @code{main}, using
-default parameters.
+@cindex @code{saveall} function attribute, Blackfin
+@cindex save all registers on the Blackfin
+@item saveall
+Use this attribute to indicate that
+all registers except the stack pointer should be saved in the prologue
+regardless of whether they are used or not.
+@end table
-Kernel functions may return an integer value, which will be written to a
-conventional place within the HSA "kernargs" region.
+@node BPF Function Attributes
+@subsection BPF Function Attributes
-The attribute parameters configure what values are passed into the kernel
-function by the GPU drivers, via the initial register state. Some values are
-used by the compiler, and therefore forced on. Enabling other options may
-break assumptions in the compiler and/or run-time libraries.
+These function attributes are supported by the BPF back end:
@table @code
-@item private_segment_buffer
-Set @code{enable_sgpr_private_segment_buffer} flag. Always on (required to
-locate the stack).
-
-@item dispatch_ptr
-Set @code{enable_sgpr_dispatch_ptr} flag. Always on (required to locate the
-launch dimensions).
-
-@item queue_ptr
-Set @code{enable_sgpr_queue_ptr} flag. Always on (required to convert address
-spaces).
-
-@item kernarg_segment_ptr
-Set @code{enable_sgpr_kernarg_segment_ptr} flag. Always on (required to
-locate the kernel arguments, "kernargs").
-
-@item dispatch_id
-Set @code{enable_sgpr_dispatch_id} flag.
-
-@item flat_scratch_init
-Set @code{enable_sgpr_flat_scratch_init} flag.
-
-@item private_segment_size
-Set @code{enable_sgpr_private_segment_size} flag.
-
-@item grid_workgroup_count_X
-Set @code{enable_sgpr_grid_workgroup_count_x} flag. Always on (required to
-use OpenACC/OpenMP).
-
-@item grid_workgroup_count_Y
-Set @code{enable_sgpr_grid_workgroup_count_y} flag.
+@cindex @code{kernel helper}, function attribute, BPF
+@item kernel_helper
+use this attribute to indicate the specified function declaration is a
+kernel helper. The helper function is passed as an argument to the
+attribute. Example:
-@item grid_workgroup_count_Z
-Set @code{enable_sgpr_grid_workgroup_count_z} flag.
+@smallexample
+int bpf_probe_read (void *dst, int size, const void *unsafe_ptr)
+ __attribute__ ((kernel_helper (4)));
+@end smallexample
-@item workgroup_id_X
-Set @code{enable_sgpr_workgroup_id_x} flag.
+@cindex @code{naked} function attribute, BPF
+@item naked
+This attribute allows the compiler to construct the requisite function
+declaration, while allowing the body of the function to be assembly
+code. The specified function will not have prologue/epilogue
+sequences generated by the compiler. Only basic @code{asm} statements
+can safely be included in naked functions (@pxref{Basic Asm}). While
+using extended @code{asm} or a mixture of basic @code{asm} and C code
+may appear to work, they cannot be depended upon to work reliably and
+are not supported.
+@end table
-@item workgroup_id_Y
-Set @code{enable_sgpr_workgroup_id_y} flag.
+@node C-SKY Function Attributes
+@subsection C-SKY Function Attributes
-@item workgroup_id_Z
-Set @code{enable_sgpr_workgroup_id_z} flag.
+These function attributes are supported by the C-SKY back end:
-@item workgroup_info
-Set @code{enable_sgpr_workgroup_info} flag.
+@table @code
+@cindex @code{interrupt} function attribute, C-SKY
+@cindex @code{isr} function attribute, C-SKY
+@item interrupt
+@itemx isr
+Use these attributes to indicate that the specified function
+is an interrupt handler.
+The compiler generates function entry and exit sequences suitable for
+use in an interrupt handler when either of these attributes are present.
-@item private_segment_wave_offset
-Set @code{enable_sgpr_private_segment_wave_byte_offset} flag. Always on
-(required to locate the stack).
+Use of these options requires the @option{-mistack} command-line option
+to enable support for the necessary interrupt stack instructions. They
+are ignored with a warning otherwise. @xref{C-SKY Options}.
-@item work_item_id_X
-Set @code{enable_vgpr_workitem_id} parameter. Always on (can't be disabled).
+@cindex @code{naked} function attribute, C-SKY
+@item naked
+This attribute allows the compiler to construct the
+requisite function declaration, while allowing the body of the
+function to be assembly code. The specified function will not have
+prologue/epilogue sequences generated by the compiler. Only basic
+@code{asm} statements can safely be included in naked functions
+(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
+basic @code{asm} and C code may appear to work, they cannot be
+depended upon to work reliably and are not supported.
+@end table
-@item work_item_id_Y
-Set @code{enable_vgpr_workitem_id} parameter. Always on (required to enable
-vectorization.)
-@item work_item_id_Z
-Set @code{enable_vgpr_workitem_id} parameter. Always on (required to use
-OpenACC/OpenMP).
+@node Epiphany Function Attributes
+@subsection Epiphany Function Attributes
-@end table
-@end table
+These function attributes are supported by the Epiphany back end:
-@node ARC Function Attributes
-@subsection ARC Function Attributes
+@table @code
+@cindex @code{disinterrupt} function attribute, Epiphany
+@item disinterrupt
+This attribute causes the compiler to emit
+instructions to disable interrupts for the duration of the given
+function.
-These function attributes are supported by the ARC back end:
+@cindex @code{forwarder_section} function attribute, Epiphany
+@item forwarder_section
+This attribute modifies the behavior of an interrupt handler.
+The interrupt handler may be in external memory which cannot be
+reached by a branch instruction, so generate a local memory trampoline
+to transfer control. The single parameter identifies the section where
+the trampoline is placed.
-@table @code
-@cindex @code{interrupt} function attribute, ARC
+@cindex @code{interrupt} function attribute, Epiphany
@item interrupt
Use this attribute to indicate
that the specified function is an interrupt handler. The compiler generates
function entry and exit sequences suitable for use in an interrupt handler
-when this attribute is present.
+when this attribute is present. It may also generate
+a special section with code to initialize the interrupt vector table.
-On the ARC, you must specify the kind of interrupt to be handled
-in a parameter to the interrupt attribute like this:
+On Epiphany targets one or more optional parameters can be added like this:
@smallexample
-void f () __attribute__ ((interrupt ("ilink1")));
+void __attribute__ ((interrupt ("dma0, dma1"))) universal_dma_handler ();
@end smallexample
-Permissible values for this parameter are: @w{@code{ilink1}} and
-@w{@code{ilink2}} for ARCv1 architecture, and @w{@code{ilink}} and
-@w{@code{firq}} for ARCv2 architecture.
-
-@cindex @code{long_call} function attribute, ARC
-@cindex @code{medium_call} function attribute, ARC
-@cindex @code{short_call} function attribute, ARC
-@cindex indirect calls, ARC
-@item long_call
-@itemx medium_call
-@itemx short_call
-These attributes specify how a particular function is called.
-These attributes override the
-@option{-mlong-calls} and @option{-mmedium-calls} (@pxref{ARC Options})
-command-line switches and @code{#pragma long_calls} settings.
+Permissible values for these parameters are: @w{@code{reset}},
+@w{@code{software_exception}}, @w{@code{page_miss}},
+@w{@code{timer0}}, @w{@code{timer1}}, @w{@code{message}},
+@w{@code{dma0}}, @w{@code{dma1}}, @w{@code{wand}} and @w{@code{swi}}.
+Multiple parameters indicate that multiple entries in the interrupt
+vector table should be initialized for this function, i.e.@: for each
+parameter @w{@var{name}}, a jump to the function is emitted in
+the section @w{ivt_entry_@var{name}}. The parameter(s) may be omitted
+entirely, in which case no interrupt vector table entry is provided.
-For ARC, a function marked with the @code{long_call} attribute is
-always called using register-indirect jump-and-link instructions,
-thereby enabling the called function to be placed anywhere within the
-32-bit address space. A function marked with the @code{medium_call}
-attribute will always be close enough to be called with an unconditional
-branch-and-link instruction, which has a 25-bit offset from
-the call site. A function marked with the @code{short_call}
-attribute will always be close enough to be called with a conditional
-branch-and-link instruction, which has a 21-bit offset from
-the call site.
-
-@cindex @code{jli_always} function attribute, ARC
-@item jli_always
-Forces a particular function to be called using @code{jli}
-instruction. The @code{jli} instruction makes use of a table stored
-into @code{.jlitab} section, which holds the location of the functions
-which are addressed using this instruction.
-
-@cindex @code{jli_fixed} function attribute, ARC
-@item jli_fixed
-Identical like the above one, but the location of the function in the
-@code{jli} table is known and given as an attribute parameter.
-
-@cindex @code{secure_call} function attribute, ARC
-@item secure_call
-This attribute allows one to mark secure-code functions that are
-callable from normal mode. The location of the secure call function
-into the @code{sjli} table needs to be passed as argument.
+Note that interrupts are enabled inside the function
+unless the @code{disinterrupt} attribute is also specified.
-@cindex @code{naked} function attribute, ARC
-@item naked
-This attribute allows the compiler to construct the requisite function
-declaration, while allowing the body of the function to be assembly
-code. The specified function will not have prologue/epilogue
-sequences generated by the compiler. Only basic @code{asm} statements
-can safely be included in naked functions (@pxref{Basic Asm}). While
-using extended @code{asm} or a mixture of basic @code{asm} and C code
-may appear to work, they cannot be depended upon to work reliably and
-are not supported.
+The following examples are all valid uses of these attributes on
+Epiphany targets:
+@smallexample
+void __attribute__ ((interrupt)) universal_handler ();
+void __attribute__ ((interrupt ("dma1"))) dma1_handler ();
+void __attribute__ ((interrupt ("dma0, dma1")))
+ universal_dma_handler ();
+void __attribute__ ((interrupt ("timer0"), disinterrupt))
+ fast_timer_handler ();
+void __attribute__ ((interrupt ("dma0, dma1"),
+ forwarder_section ("tramp")))
+ external_dma_handler ();
+@end smallexample
+@cindex @code{long_call} function attribute, Epiphany
+@cindex @code{short_call} function attribute, Epiphany
+@cindex indirect calls, Epiphany
+@item long_call
+@itemx short_call
+These attributes specify how a particular function is called.
+These attributes override the
+@option{-mlong-calls} (@pxref{Adapteva Epiphany Options})
+command-line switch and @code{#pragma long_calls} settings.
@end table
-@node ARM Function Attributes
-@subsection ARM Function Attributes
-
-These function attributes are supported for ARM targets:
-
-@table @code
-
-@cindex @code{general-regs-only} function attribute, ARM
-@item general-regs-only
-Indicates that no floating-point or Advanced SIMD registers should be
-used when generating code for this function. If the function explicitly
-uses floating-point code, then the compiler gives an error. This is
-the same behavior as that of the command-line option
-@option{-mgeneral-regs-only}.
-
-@cindex @code{interrupt} function attribute, ARM
-@item interrupt
-Use this attribute to indicate
-that the specified function is an interrupt handler. The compiler generates
-function entry and exit sequences suitable for use in an interrupt handler
-when this attribute is present.
-
-You can specify the kind of interrupt to be handled by
-adding an optional parameter to the interrupt attribute like this:
-@smallexample
-void f () __attribute__ ((interrupt ("IRQ")));
-@end smallexample
+@node H8/300 Function Attributes
+@subsection H8/300 Function Attributes
-@noindent
-Permissible values for this parameter are: @code{IRQ}, @code{FIQ},
-@code{SWI}, @code{ABORT} and @code{UNDEF}.
+These function attributes are available for H8/300 targets:
-On ARMv7-M the interrupt type is ignored, and the attribute means the function
-may be called with a word-aligned stack pointer.
+@table @code
+@cindex @code{function_vector} function attribute, H8/300
+@item function_vector
+Use this attribute on the H8/300, H8/300H, and H8S to indicate
+that the specified function should be called through the function vector.
+Calling a function through the function vector reduces code size; however,
+the function vector has a limited size (maximum 128 entries on the H8/300
+and 64 entries on the H8/300H and H8S)
+and shares space with the interrupt vector.
-@cindex @code{isr} function attribute, ARM
-@item isr
-Use this attribute on ARM to write Interrupt Service Routines. This is an
-alias to the @code{interrupt} attribute above.
+@cindex @code{interrupt_handler} function attribute, H8/300
+@item interrupt_handler
+Use this attribute on the H8/300, H8/300H, and H8S to
+indicate that the specified function is an interrupt handler. The compiler
+generates function entry and exit sequences suitable for use in an
+interrupt handler when this attribute is present.
-@cindex @code{long_call} function attribute, ARM
-@cindex @code{short_call} function attribute, ARM
-@cindex indirect calls, ARM
-@item long_call
-@itemx short_call
-These attributes specify how a particular function is called.
-These attributes override the
-@option{-mlong-calls} (@pxref{ARM Options})
-command-line switch and @code{#pragma long_calls} settings. For ARM, the
-@code{long_call} attribute indicates that the function might be far
-away from the call site and require a different (more expensive)
-calling sequence. The @code{short_call} attribute always places
-the offset to the function from the call site into the @samp{BL}
-instruction directly.
+@cindex @code{saveall} function attribute, H8/300
+@cindex save all registers on the H8/300, H8/300H, and H8S
+@item saveall
+Use this attribute on the H8/300, H8/300H, and H8S to indicate that
+all registers except the stack pointer should be saved in the prologue
+regardless of whether they are used or not.
+@end table
-@cindex @code{naked} function attribute, ARM
-@item naked
-This attribute allows the compiler to construct the
-requisite function declaration, while allowing the body of the
-function to be assembly code. The specified function will not have
-prologue/epilogue sequences generated by the compiler. Only basic
-@code{asm} statements can safely be included in naked functions
-(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
-basic @code{asm} and C code may appear to work, they cannot be
-depended upon to work reliably and are not supported.
+@node IA-64 Function Attributes
+@subsection IA-64 Function Attributes
-@cindex @code{pcs} function attribute, ARM
-@item pcs
+These function attributes are supported on IA-64 targets:
-The @code{pcs} attribute can be used to control the calling convention
-used for a function on ARM. The attribute takes an argument that specifies
-the calling convention to use.
+@table @code
+@cindex @code{syscall_linkage} function attribute, IA-64
+@item syscall_linkage
+This attribute is used to modify the IA-64 calling convention by marking
+all input registers as live at all function exits. This makes it possible
+to restart a system call after an interrupt without having to save/restore
+the input registers. This also prevents kernel data from leaking into
+application code.
-When compiling using the AAPCS ABI (or a variant of it) then valid
-values for the argument are @code{"aapcs"} and @code{"aapcs-vfp"}. In
-order to use a variant other than @code{"aapcs"} then the compiler must
-be permitted to use the appropriate co-processor registers (i.e., the
-VFP registers must be available in order to use @code{"aapcs-vfp"}).
-For example,
+@cindex @code{version_id} function attribute, IA-64
+@item version_id
+This IA-64 HP-UX attribute, attached to a global variable or function, renames a
+symbol to contain a version string, thus allowing for function level
+versioning. HP-UX system header files may use function level versioning
+for some system calls.
@smallexample
-/* Argument passed in r0, and result returned in r0+r1. */
-double f2d (float) __attribute__((pcs("aapcs")));
+extern int foo () __attribute__((version_id ("20040821")));
@end smallexample
-Variadic functions always use the @code{"aapcs"} calling convention and
-the compiler rejects attempts to specify an alternative.
-
-@cindex @code{target} function attribute
-@item target (@var{options})
-As discussed in @ref{Common Function Attributes}, this attribute
-allows specification of target-specific compilation options.
-
-On ARM, the following options are allowed:
+@noindent
+Calls to @code{foo} are mapped to calls to @code{foo@{20040821@}}.
+@end table
-@table @samp
-@cindex @code{target("thumb")} function attribute, ARM
-@item thumb
-Force code generation in the Thumb (T16/T32) ISA, depending on the
-architecture level.
+@node LoongArch Function Attributes
+@subsection LoongArch Function Attributes
-@cindex @code{target("arm")} function attribute, ARM
-@item arm
-Force code generation in the ARM (A32) ISA.
+These function attributes are supported by the LoongArch end:
-Functions from different modes can be inlined in the caller's mode.
+@table @code
+@cindex @code{strict-align} function attribute, LoongArch
+@item strict-align
+@itemx no-strict-align
+@code{strict-align} indicates that the compiler should not assume that unaligned
+memory references are handled by the system. To allow the compiler to assume
+that aligned memory references are handled by the system, the inverse attribute
+@code{no-strict-align} can be specified. The behavior is same as for the
+command-line option @option{-mstrict-align} and @option{-mno-strict-align}.
-@cindex @code{target("fpu=")} function attribute, ARM
-@item fpu=
-Specifies the fpu for which to tune the performance of this function.
-The behavior and permissible arguments are the same as for the @option{-mfpu=}
-command-line option.
+@cindex @code{cmodel=} function attribute, LoongArch
+@item cmodel=
+Indicates that code should be generated for a particular code model for
+this function. The behavior and permissible arguments are the same as
+for the command-line option @option{-mcmodel=}.
-@cindex @code{arch=} function attribute, ARM
+@cindex @code{arch=} function attribute, LoongArch
@item arch=
Specifies the architecture version and architectural extensions to use
for this function. The behavior and permissible arguments are the same as
for the @option{-march=} command-line option.
-The above target attributes can be specified as follows:
+@cindex @code{tune=} function attribute, LoongArch
+@item tune=
+Specifies the core for which to tune the performance of this function.
+The behavior and permissible arguments are the same as for the @option{-mtune=}
+command-line option.
-@smallexample
-__attribute__((target("arch=armv8-a+crc")))
-int
-f (int a)
-@{
- return a + 5;
-@}
-@end smallexample
+@cindex @code{lsx} function attribute, LoongArch
+@item lsx
+@itemx no-lsx
+@code{lsx} indicates that vector instruction generation is allowed (not allowed)
+when compiling the function. The behavior is same as for the command-line option
+@option{-mlsx} and @option{-mno-lsx}.
-Additionally, the architectural extension string may be specified on its
-own. This can be used to turn on and off particular architectural extensions
-without having to specify a particular architecture version or core. Example:
+@cindex @code{lasx} function attribute, LoongArch
+@item lasx
+@itemx no-lasx
+@code{lasx} indicates that lasx instruction generation is allowed (not allowed)
+when compiling the function. The behavior is slightly different from the
+command-line option @option{-mno-lasx}.
+Example:
@smallexample
-__attribute__((target("+crc+nocrypto")))
-int
-foo (int a)
+test.c:
+typedef int v4i32 __attribute__ ((vector_size(16), aligned(16)));
+
+v4i32 a, b, c;
+#ifdef WITH_ATTR
+__attribute__ ((target("no-lasx"))) void
+#else
+void
+#endif
+test ()
@{
- return a + 5;
+ c = a + b;
@}
@end smallexample
-
-In this example @code{target("+crc+nocrypto")} enables the @code{crc}
-extension and disables the @code{crypto} extension for the function @code{foo}
-without modifying an existing @option{-march=} or @option{-mcpu} option.
-
-@end table
+@smallexample
+$ gcc test.c -o test.s -O2 -mlasx -DWITH_ATTR
+@end smallexample
+Compiled as above, 128-bit vectorization is possible.
+But the following method cannot perform 128-bit vectorization.
+@smallexample
+$ gcc test.c -o test.s -O2 -mlasx -mno-lasx
+@end smallexample
@end table
-@node AVR Function Attributes
-@subsection AVR Function Attributes
+@node M32C Function Attributes
+@subsection M32C Function Attributes
-These function attributes are supported by the AVR back end:
+These function attributes are supported by the M32C back end:
@table @code
-@cindex @code{signal} function attribute, AVR
-@cindex @code{interrupt} function attribute, AVR
-@item signal
-@itemx interrupt
-The function is an interrupt service routine (ISR). The compiler generates
-function entry and exit sequences suitable for use in an interrupt handler
-when one of the attributes is present.
-
-The AVR hardware globally disables interrupts when an interrupt is executed.
+@cindex @code{bank_switch} function attribute, M32C
+@item bank_switch
+When added to an interrupt handler with the M32C port, causes the
+prologue and epilogue to use bank switching to preserve the registers
+rather than saving them on the stack.
-@itemize @bullet
-@item ISRs with the @code{signal} attribute do not re-enable interrupts.
-It is save to enable interrupts in a @code{signal} handler.
-This ``save'' only applies to the code
-generated by the compiler and not to the IRQ layout of the
-application which is responsibility of the application.
+@cindex @code{fast_interrupt} function attribute, M32C
+@item fast_interrupt
+Use this attribute on the M32C port to indicate that the specified
+function is a fast interrupt handler. This is just like the
+@code{interrupt} attribute, except that @code{freit} is used to return
+instead of @code{reit}.
-@item ISRs with the @code{interrupt} attribute re-enable interrupts.
-The first instruction of the routine is a @code{SEI} instruction to
-globally enable interrupts.
-@end itemize
+@cindex @code{function_vector} function attribute, M16C/M32C
+@item function_vector
+On M16C/M32C targets, the @code{function_vector} attribute declares a
+special page subroutine call function. Use of this attribute reduces
+the code size by 2 bytes for each call generated to the
+subroutine. The argument to the attribute is the vector number entry
+from the special page vector table which contains the 16 low-order
+bits of the subroutine's entry address. Each vector table has special
+page number (18 to 255) that is used in @code{jsrs} instructions.
+Jump addresses of the routines are generated by adding 0x0F0000 (in
+case of M16C targets) or 0xFF0000 (in case of M32C targets), to the
+2-byte addresses set in the vector table. Therefore you need to ensure
+that all the special page vector routines should get mapped within the
+address range 0x0F0000 to 0x0FFFFF (for M16C) and 0xFF0000 to 0xFFFFFF
+(for M32C).
-The recommended way to use these attributes is by means of the
-@code{ISR} macro provided by @code{avr/interrupt.h} from
-@w{@uref{https://avrdudes.github.io/avr-libc/avr-libc-user-manual/group__avr__interrupts.html,,AVR-LibC}}:
-@example
-#include <avr/interrupt.h>
+In the following example 2 bytes are saved for each call to
+function @code{foo}.
-ISR (INT0_vect) // Uses the "signal" attribute.
+@smallexample
+void foo (void) __attribute__((function_vector(0x18)));
+void foo (void)
@{
- // Code
@}
-ISR (ADC_vect, ISR_NOBLOCK) // Uses the "interrupt" attribute.
+void bar (void)
@{
- // Code
+ foo();
@}
-@end example
+@end smallexample
-When both @code{signal} and @code{interrupt} are specified for the same
-function, then @code{signal} is silently ignored.
+If functions are defined in one file and are called in another file,
+then be sure to write this declaration in both files.
-@cindex @code{signal(@var{num})} function attribute, AVR
-@cindex @code{interrupt(@var{num})} function attribute, AVR
-@item signal(@var{num})
-@itemx interrupt(@var{num})
+This attribute is ignored for R8C target.
-Similar to the @code{signal} resp. @code{interrupt} attribute without
-argument, but the IRQ number is supplied as an argument @var{num} to
-the attribute, rather than providing the ISR name itself as the function name:
+@cindex @code{interrupt} function attribute, M32C
+@item interrupt
+Use this attribute to indicate
+that the specified function is an interrupt handler. The compiler generates
+function entry and exit sequences suitable for use in an interrupt handler
+when this attribute is present.
+@end table
-@example
-__attribute__((signal(1)))
-static void my_handler (void)
-@{
- // Code for __vector_1
-@}
-@end example
+@node M32R/D Function Attributes
+@subsection M32R/D Function Attributes
-Notice that the handler function needs not to be externally visible.
-The recommended way to use these attributes is by means of the
-@code{ISR_N} macro provided by @code{avr/interrupt.h} from
-@w{@uref{https://avrdudes.github.io/avr-libc/avr-libc-user-manual/group__avr__interrupts.html,,AVR-LibC}}:
+These function attributes are supported by the M32R/D back end:
-@example
-#include <avr/interrupt.h>
+@table @code
+@cindex @code{interrupt} function attribute, M32R/D
+@item interrupt
+Use this attribute to indicate
+that the specified function is an interrupt handler. The compiler generates
+function entry and exit sequences suitable for use in an interrupt handler
+when this attribute is present.
-ISR_N (PCINT0_vect_num)
-static void my_pcint0_handler (void)
-@{
- // Code
-@}
+@cindex @code{model} function attribute, M32R/D
+@cindex function addressability on the M32R/D
+@item model (@var{model-name})
-ISR_N (ADC_vect_num, ISR_NOBLOCK)
-static void my_adc_handler (void)
-@{
- // Code
-@}
-@end example
+On the M32R/D, use this attribute to set the addressability of an
+object, and of the code generated for a function. The identifier
+@var{model-name} is one of @code{small}, @code{medium}, or
+@code{large}, representing each of the code models.
-@code{ISR_N} can be specified more than once, in which case several
-interrupt vectors are pointing to the same handler function. This
-is similar to the @code{ISR_ALIASOF} macro provided by AVR-LibC, but
-without the overhead introduced by @code{ISR_ALIASOF}.
+Small model objects live in the lower 16MB of memory (so that their
+addresses can be loaded with the @code{ld24} instruction), and are
+callable with the @code{bl} instruction.
+Medium model objects may live anywhere in the 32-bit address space (the
+compiler generates @code{seth/add3} instructions to load their addresses),
+and are callable with the @code{bl} instruction.
-@cindex @code{noblock} function attribute, AVR
-@item noblock
+Large model objects may live anywhere in the 32-bit address space (the
+compiler generates @code{seth/add3} instructions to load their addresses),
+and may not be reachable with the @code{bl} instruction (the compiler
+generates the much slower @code{seth/add3/jl} instruction sequence).
+@end table
-This attribute can be used together with the @code{signal} attribute
-to indicate that an interrupt service routine should start with a @code{SEI}
-instruction to globally re-enable interrupts. Using attributes @code{signal}
-and @code{noblock} together has the same effect like using the @code{interrupt}
-attribute. Using the @code{noblock} attribute without @code{signal} has no
-effect.
+@node m68k Function Attributes
+@subsection m68k Function Attributes
-@cindex @code{naked} function attribute, AVR
+These function attributes are supported by the m68k back end:
+
+@table @code
+@cindex @code{interrupt} function attribute, m68k
+@cindex @code{interrupt_handler} function attribute, m68k
+@item interrupt
+@itemx interrupt_handler
+Use this attribute to
+indicate that the specified function is an interrupt handler. The compiler
+generates function entry and exit sequences suitable for use in an
+interrupt handler when this attribute is present. Either name may be used.
+
+@cindex @code{interrupt_thread} function attribute, fido
+@item interrupt_thread
+Use this attribute on fido, a subarchitecture of the m68k, to indicate
+that the specified function is an interrupt handler that is designed
+to run as a thread. The compiler omits generate prologue/epilogue
+sequences and replaces the return instruction with a @code{sleep}
+instruction. This attribute is available only on fido.
+@end table
+
+@node MCORE Function Attributes
+@subsection MCORE Function Attributes
+
+These function attributes are supported by the MCORE back end:
+
+@table @code
+@cindex @code{naked} function attribute, MCORE
@item naked
This attribute allows the compiler to construct the
requisite function declaration, while allowing the body of the
(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
basic @code{asm} and C code may appear to work, they cannot be
depended upon to work reliably and are not supported.
+@end table
-@cindex @code{no_gccisr} function attribute, AVR
-@item no_gccisr
-Do not use the @code{__gcc_isr}
-@uref{https://sourceware.org/binutils/docs/as/AVR-Pseudo-Instructions.html,pseudo instruction}
-in a function with
-the @code{interrupt} or @code{signal} attribute aka. interrupt
-service routine (ISR).
-Use this attribute if the preamble of the ISR prologue should always read
-@example
-push __zero_reg__
-push __tmp_reg__
-in __tmp_reg__, __SREG__
-push __tmp_reg__
-clr __zero_reg__
-@end example
-and accordingly for the postamble of the epilogue --- no matter whether
-the mentioned registers are actually used in the ISR or not.
-Situations where you might want to use this attribute include:
-@itemize @bullet
-@item
-Code that (effectively) clobbers bits of @code{SREG} other than the
-@code{I}-flag by writing to the memory location of @code{SREG}.
-@item
-Code that uses inline assembler to jump to a different function which
-expects (parts of) the prologue code as outlined above to be present.
-@end itemize
-To disable @code{__gcc_isr} generation for the whole compilation unit,
-there is option @option{-mno-gas-isr-prologues}, @pxref{AVR Options}.
-
-@cindex @code{OS_main} function attribute, AVR
-@cindex @code{OS_task} function attribute, AVR
-@item OS_main
-@itemx OS_task
-On AVR, functions with the @code{OS_main} or @code{OS_task} attribute
-do not save/restore any call-saved register in their prologue/epilogue.
+@node MicroBlaze Function Attributes
+@subsection MicroBlaze Function Attributes
-The @code{OS_main} attribute can be used when there @emph{is
-guarantee} that interrupts are disabled at the time when the function
-is entered. This saves resources when the stack pointer has to be
-changed to set up a frame for local variables.
+These function attributes are supported on MicroBlaze targets:
-The @code{OS_task} attribute can be used when there is @emph{no
-guarantee} that interrupts are disabled at that time when the function
-is entered like for, e@.g@. task functions in a multi-threading operating
-system. In that case, changing the stack pointer register is
-guarded by save/clear/restore of the global interrupt enable flag.
+@table @code
+@cindex @code{save_volatiles} function attribute, MicroBlaze
+@item save_volatiles
+Use this attribute to indicate that the function is
+an interrupt handler. All volatile registers (in addition to non-volatile
+registers) are saved in the function prologue. If the function is a leaf
+function, only volatiles used by the function are saved. A normal function
+return is generated instead of a return from interrupt.
-The differences to the @code{naked} function attribute are:
-@itemize @bullet
-@item @code{naked} functions do not have a return instruction whereas
-@code{OS_main} and @code{OS_task} functions have a @code{RET} or
-@code{RETI} return instruction.
-@item @code{naked} functions do not set up a frame for local variables
-or a frame pointer whereas @code{OS_main} and @code{OS_task} do this
-as needed.
-@end itemize
+@cindex @code{break_handler} function attribute, MicroBlaze
+@cindex break handler functions
+@item break_handler
+Use this attribute to indicate that
+the specified function is a break handler. The compiler generates function
+entry and exit sequences suitable for use in an break handler when this
+attribute is present. The return from @code{break_handler} is done through
+the @code{rtbd} instead of @code{rtsd}.
+
+@smallexample
+void f () __attribute__ ((break_handler));
+@end smallexample
+@cindex @code{interrupt_handler} function attribute, MicroBlaze
+@cindex @code{fast_interrupt} function attribute, MicroBlaze
+@item interrupt_handler
+@itemx fast_interrupt
+These attributes indicate that the specified function is an interrupt
+handler. Use the @code{fast_interrupt} attribute to indicate handlers
+used in low-latency interrupt mode, and @code{interrupt_handler} for
+interrupts that do not use low-latency handlers. In both cases, GCC
+emits appropriate prologue code and generates a return from the handler
+using @code{rtid} instead of @code{rtsd}.
@end table
-@node Blackfin Function Attributes
-@subsection Blackfin Function Attributes
+@node Microsoft Windows Function Attributes
+@subsection Microsoft Windows Function Attributes
-These function attributes are supported by the Blackfin back end:
+The following attributes are available on Microsoft Windows and Symbian OS
+targets.
@table @code
+@cindex @code{dllexport} function attribute
+@cindex @code{__declspec(dllexport)}
+@item dllexport
+On Microsoft Windows targets and Symbian OS targets the
+@code{dllexport} attribute causes the compiler to provide a global
+pointer to a pointer in a DLL, so that it can be referenced with the
+@code{dllimport} attribute. On Microsoft Windows targets, the pointer
+name is formed by combining @code{_imp__} and the function or variable
+name.
-@cindex @code{exception_handler} function attribute
-@cindex exception handler functions, Blackfin
-@item exception_handler
-Use this attribute on the Blackfin to indicate that the specified function
-is an exception handler. The compiler generates function entry and
-exit sequences suitable for use in an exception handler when this
-attribute is present.
+You can use @code{__declspec(dllexport)} as a synonym for
+@code{__attribute__ ((dllexport))} for compatibility with other
+compilers.
-@cindex @code{interrupt_handler} function attribute, Blackfin
-@item interrupt_handler
-Use this attribute to
-indicate that the specified function is an interrupt handler. The compiler
-generates function entry and exit sequences suitable for use in an
-interrupt handler when this attribute is present.
+On systems that support the @code{visibility} attribute, this
+attribute also implies ``default'' visibility. It is an error to
+explicitly specify any other visibility.
-@cindex @code{kspisusp} function attribute, Blackfin
-@cindex User stack pointer in interrupts on the Blackfin
-@item kspisusp
-When used together with @code{interrupt_handler}, @code{exception_handler}
-or @code{nmi_handler}, code is generated to load the stack pointer
-from the USP register in the function prologue.
+GCC's default behavior is to emit all inline functions with the
+@code{dllexport} attribute. Since this can cause object file-size bloat,
+you can use @option{-fno-keep-inline-dllexport}, which tells GCC to
+ignore the attribute for inlined functions unless the
+@option{-fkeep-inline-functions} flag is used instead.
-@cindex @code{l1_text} function attribute, Blackfin
-@item l1_text
-This attribute specifies a function to be placed into L1 Instruction
-SRAM@. The function is put into a specific section named @code{.l1.text}.
-With @option{-mfdpic}, function calls with a such function as the callee
-or caller uses inlined PLT.
+The attribute is ignored for undefined symbols.
-@cindex @code{l2} function attribute, Blackfin
-@item l2
-This attribute specifies a function to be placed into L2
-SRAM. The function is put into a specific section named
-@code{.l2.text}. With @option{-mfdpic}, callers of such functions use
-an inlined PLT.
+When applied to C++ classes, the attribute marks defined non-inlined
+member functions and static data members as exports. Static consts
+initialized in-class are not marked unless they are also defined
+out-of-class.
-@cindex indirect calls, Blackfin
-@cindex @code{longcall} function attribute, Blackfin
-@cindex @code{shortcall} function attribute, Blackfin
-@item longcall
-@itemx shortcall
-The @code{longcall} attribute
-indicates that the function might be far away from the call site and
-require a different (more expensive) calling sequence. The
-@code{shortcall} attribute indicates that the function is always close
-enough for the shorter calling sequence to be used. These attributes
-override the @option{-mlongcall} switch.
+For Microsoft Windows targets there are alternative methods for
+including the symbol in the DLL's export table such as using a
+@file{.def} file with an @code{EXPORTS} section or, with GNU ld, using
+the @option{--export-all} linker flag.
-@cindex @code{nesting} function attribute, Blackfin
-@cindex Allow nesting in an interrupt handler on the Blackfin processor
-@item nesting
-Use this attribute together with @code{interrupt_handler},
-@code{exception_handler} or @code{nmi_handler} to indicate that the function
-entry code should enable nested interrupts or exceptions.
+@cindex @code{dllimport} function attribute
+@cindex @code{__declspec(dllimport)}
+@item dllimport
+On Microsoft Windows and Symbian OS targets, the @code{dllimport}
+attribute causes the compiler to reference a function or variable via
+a global pointer to a pointer that is set up by the DLL exporting the
+symbol. The attribute implies @code{extern}. On Microsoft Windows
+targets, the pointer name is formed by combining @code{_imp__} and the
+function or variable name.
-@cindex @code{nmi_handler} function attribute, Blackfin
-@cindex NMI handler functions on the Blackfin processor
-@item nmi_handler
-Use this attribute on the Blackfin to indicate that the specified function
-is an NMI handler. The compiler generates function entry and
-exit sequences suitable for use in an NMI handler when this
-attribute is present.
+You can use @code{__declspec(dllimport)} as a synonym for
+@code{__attribute__ ((dllimport))} for compatibility with other
+compilers.
-@cindex @code{saveall} function attribute, Blackfin
-@cindex save all registers on the Blackfin
-@item saveall
-Use this attribute to indicate that
-all registers except the stack pointer should be saved in the prologue
-regardless of whether they are used or not.
-@end table
+On systems that support the @code{visibility} attribute, this
+attribute also implies ``default'' visibility. It is an error to
+explicitly specify any other visibility.
-@node BPF Function Attributes
-@subsection BPF Function Attributes
+Currently, the attribute is ignored for inlined functions. If the
+attribute is applied to a symbol @emph{definition}, an error is reported.
+If a symbol previously declared @code{dllimport} is later defined, the
+attribute is ignored in subsequent references, and a warning is emitted.
+The attribute is also overridden by a subsequent declaration as
+@code{dllexport}.
-These function attributes are supported by the BPF back end:
+When applied to C++ classes, the attribute marks non-inlined
+member functions and static data members as imports. However, the
+attribute is ignored for virtual methods to allow creation of vtables
+using thunks.
-@table @code
-@cindex @code{kernel helper}, function attribute, BPF
-@item kernel_helper
-use this attribute to indicate the specified function declaration is a
-kernel helper. The helper function is passed as an argument to the
-attribute. Example:
+On the SH Symbian OS target the @code{dllimport} attribute also has
+another affect---it can cause the vtable and run-time type information
+for a class to be exported. This happens when the class has a
+dllimported constructor or a non-inline, non-pure virtual function
+and, for either of those two conditions, the class also has an inline
+constructor or destructor and has a key function that is defined in
+the current translation unit.
-@smallexample
-int bpf_probe_read (void *dst, int size, const void *unsafe_ptr)
- __attribute__ ((kernel_helper (4)));
-@end smallexample
+For Microsoft Windows targets the use of the @code{dllimport}
+attribute on functions is not necessary, but provides a small
+performance benefit by eliminating a thunk in the DLL@. The use of the
+@code{dllimport} attribute on imported variables can be avoided by passing the
+@option{--enable-auto-import} switch to the GNU linker. As with
+functions, using the attribute for a variable eliminates a thunk in
+the DLL@.
-@cindex @code{naked} function attribute, BPF
-@item naked
-This attribute allows the compiler to construct the requisite function
-declaration, while allowing the body of the function to be assembly
-code. The specified function will not have prologue/epilogue
-sequences generated by the compiler. Only basic @code{asm} statements
-can safely be included in naked functions (@pxref{Basic Asm}). While
-using extended @code{asm} or a mixture of basic @code{asm} and C code
-may appear to work, they cannot be depended upon to work reliably and
-are not supported.
+One drawback to using this attribute is that a pointer to a
+@emph{variable} marked as @code{dllimport} cannot be used as a constant
+address. However, a pointer to a @emph{function} with the
+@code{dllimport} attribute can be used as a constant initializer; in
+this case, the address of a stub function in the import lib is
+referenced. On Microsoft Windows targets, the attribute can be disabled
+for functions by setting the @option{-mnop-fun-dllimport} flag.
@end table
-@node C-SKY Function Attributes
-@subsection C-SKY Function Attributes
+@node MIPS Function Attributes
+@subsection MIPS Function Attributes
-These function attributes are supported by the C-SKY back end:
+These function attributes are supported by the MIPS back end:
@table @code
-@cindex @code{interrupt} function attribute, C-SKY
-@cindex @code{isr} function attribute, C-SKY
+@cindex @code{interrupt} function attribute, MIPS
@item interrupt
-@itemx isr
-Use these attributes to indicate that the specified function
-is an interrupt handler.
-The compiler generates function entry and exit sequences suitable for
-use in an interrupt handler when either of these attributes are present.
+Use this attribute to indicate that the specified function is an interrupt
+handler. The compiler generates function entry and exit sequences suitable
+for use in an interrupt handler when this attribute is present.
+An optional argument is supported for the interrupt attribute which allows
+the interrupt mode to be described. By default GCC assumes the external
+interrupt controller (EIC) mode is in use, this can be explicitly set using
+@code{eic}. When interrupts are non-masked then the requested Interrupt
+Priority Level (IPL) is copied to the current IPL which has the effect of only
+enabling higher priority interrupts. To use vectored interrupt mode use
+the argument @code{vector=[sw0|sw1|hw0|hw1|hw2|hw3|hw4|hw5]}, this will change
+the behavior of the non-masked interrupt support and GCC will arrange to mask
+all interrupts from sw0 up to and including the specified interrupt vector.
-Use of these options requires the @option{-mistack} command-line option
-to enable support for the necessary interrupt stack instructions. They
-are ignored with a warning otherwise. @xref{C-SKY Options}.
+You can use the following attributes to modify the behavior
+of an interrupt handler:
+@table @code
+@cindex @code{use_shadow_register_set} function attribute, MIPS
+@item use_shadow_register_set
+Assume that the handler uses a shadow register set, instead of
+the main general-purpose registers. An optional argument @code{intstack} is
+supported to indicate that the shadow register set contains a valid stack
+pointer.
-@cindex @code{naked} function attribute, C-SKY
-@item naked
-This attribute allows the compiler to construct the
-requisite function declaration, while allowing the body of the
-function to be assembly code. The specified function will not have
-prologue/epilogue sequences generated by the compiler. Only basic
-@code{asm} statements can safely be included in naked functions
-(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
-basic @code{asm} and C code may appear to work, they cannot be
-depended upon to work reliably and are not supported.
-@end table
-
-
-@node Epiphany Function Attributes
-@subsection Epiphany Function Attributes
-
-These function attributes are supported by the Epiphany back end:
-
-@table @code
-@cindex @code{disinterrupt} function attribute, Epiphany
-@item disinterrupt
-This attribute causes the compiler to emit
-instructions to disable interrupts for the duration of the given
-function.
-
-@cindex @code{forwarder_section} function attribute, Epiphany
-@item forwarder_section
-This attribute modifies the behavior of an interrupt handler.
-The interrupt handler may be in external memory which cannot be
-reached by a branch instruction, so generate a local memory trampoline
-to transfer control. The single parameter identifies the section where
-the trampoline is placed.
-
-@cindex @code{interrupt} function attribute, Epiphany
-@item interrupt
-Use this attribute to indicate
-that the specified function is an interrupt handler. The compiler generates
-function entry and exit sequences suitable for use in an interrupt handler
-when this attribute is present. It may also generate
-a special section with code to initialize the interrupt vector table.
-
-On Epiphany targets one or more optional parameters can be added like this:
-
-@smallexample
-void __attribute__ ((interrupt ("dma0, dma1"))) universal_dma_handler ();
-@end smallexample
-
-Permissible values for these parameters are: @w{@code{reset}},
-@w{@code{software_exception}}, @w{@code{page_miss}},
-@w{@code{timer0}}, @w{@code{timer1}}, @w{@code{message}},
-@w{@code{dma0}}, @w{@code{dma1}}, @w{@code{wand}} and @w{@code{swi}}.
-Multiple parameters indicate that multiple entries in the interrupt
-vector table should be initialized for this function, i.e.@: for each
-parameter @w{@var{name}}, a jump to the function is emitted in
-the section @w{ivt_entry_@var{name}}. The parameter(s) may be omitted
-entirely, in which case no interrupt vector table entry is provided.
+@cindex @code{keep_interrupts_masked} function attribute, MIPS
+@item keep_interrupts_masked
+Keep interrupts masked for the whole function. Without this attribute,
+GCC tries to reenable interrupts for as much of the function as it can.
-Note that interrupts are enabled inside the function
-unless the @code{disinterrupt} attribute is also specified.
+@cindex @code{use_debug_exception_return} function attribute, MIPS
+@item use_debug_exception_return
+Return using the @code{deret} instruction. Interrupt handlers that don't
+have this attribute return using @code{eret} instead.
+@end table
-The following examples are all valid uses of these attributes on
-Epiphany targets:
+You can use any combination of these attributes, as shown below:
@smallexample
-void __attribute__ ((interrupt)) universal_handler ();
-void __attribute__ ((interrupt ("dma1"))) dma1_handler ();
-void __attribute__ ((interrupt ("dma0, dma1")))
- universal_dma_handler ();
-void __attribute__ ((interrupt ("timer0"), disinterrupt))
- fast_timer_handler ();
-void __attribute__ ((interrupt ("dma0, dma1"),
- forwarder_section ("tramp")))
- external_dma_handler ();
+void __attribute__ ((interrupt)) v0 ();
+void __attribute__ ((interrupt, use_shadow_register_set)) v1 ();
+void __attribute__ ((interrupt, keep_interrupts_masked)) v2 ();
+void __attribute__ ((interrupt, use_debug_exception_return)) v3 ();
+void __attribute__ ((interrupt, use_shadow_register_set,
+ keep_interrupts_masked)) v4 ();
+void __attribute__ ((interrupt, use_shadow_register_set,
+ use_debug_exception_return)) v5 ();
+void __attribute__ ((interrupt, keep_interrupts_masked,
+ use_debug_exception_return)) v6 ();
+void __attribute__ ((interrupt, use_shadow_register_set,
+ keep_interrupts_masked,
+ use_debug_exception_return)) v7 ();
+void __attribute__ ((interrupt("eic"))) v8 ();
+void __attribute__ ((interrupt("vector=hw3"))) v9 ();
@end smallexample
-@cindex @code{long_call} function attribute, Epiphany
-@cindex @code{short_call} function attribute, Epiphany
-@cindex indirect calls, Epiphany
+@cindex indirect calls, MIPS
+@cindex @code{long_call} function attribute, MIPS
+@cindex @code{short_call} function attribute, MIPS
+@cindex @code{near} function attribute, MIPS
+@cindex @code{far} function attribute, MIPS
@item long_call
@itemx short_call
-These attributes specify how a particular function is called.
-These attributes override the
-@option{-mlong-calls} (@pxref{Adapteva Epiphany Options})
-command-line switch and @code{#pragma long_calls} settings.
-@end table
-
+@itemx near
+@itemx far
+These attributes specify how a particular function is called on MIPS@.
+The attributes override the @option{-mlong-calls} (@pxref{MIPS Options})
+command-line switch. The @code{long_call} and @code{far} attributes are
+synonyms, and cause the compiler to always call
+the function by first loading its address into a register, and then using
+the contents of that register. The @code{short_call} and @code{near}
+attributes are synonyms, and have the opposite
+effect; they specify that non-PIC calls should be made using the more
+efficient @code{jal} instruction.
-@node H8/300 Function Attributes
-@subsection H8/300 Function Attributes
+@cindex @code{mips16} function attribute, MIPS
+@cindex @code{nomips16} function attribute, MIPS
+@item mips16
+@itemx nomips16
-These function attributes are available for H8/300 targets:
+On MIPS targets, you can use the @code{mips16} and @code{nomips16}
+function attributes to locally select or turn off MIPS16 code generation.
+A function with the @code{mips16} attribute is emitted as MIPS16 code,
+while MIPS16 code generation is disabled for functions with the
+@code{nomips16} attribute. These attributes override the
+@option{-mips16} and @option{-mno-mips16} options on the command line
+(@pxref{MIPS Options}).
-@table @code
-@cindex @code{function_vector} function attribute, H8/300
-@item function_vector
-Use this attribute on the H8/300, H8/300H, and H8S to indicate
-that the specified function should be called through the function vector.
-Calling a function through the function vector reduces code size; however,
-the function vector has a limited size (maximum 128 entries on the H8/300
-and 64 entries on the H8/300H and H8S)
-and shares space with the interrupt vector.
+When compiling files containing mixed MIPS16 and non-MIPS16 code, the
+preprocessor symbol @code{__mips16} reflects the setting on the command line,
+not that within individual functions. Mixed MIPS16 and non-MIPS16 code
+may interact badly with some GCC extensions such as @code{__builtin_apply}
+(@pxref{Constructing Calls}).
-@cindex @code{interrupt_handler} function attribute, H8/300
-@item interrupt_handler
-Use this attribute on the H8/300, H8/300H, and H8S to
-indicate that the specified function is an interrupt handler. The compiler
-generates function entry and exit sequences suitable for use in an
-interrupt handler when this attribute is present.
+@cindex @code{micromips} function attribute
+@cindex @code{nomicromips} function attribute
+@item micromips, MIPS
+@itemx nomicromips, MIPS
-@cindex @code{saveall} function attribute, H8/300
-@cindex save all registers on the H8/300, H8/300H, and H8S
-@item saveall
-Use this attribute on the H8/300, H8/300H, and H8S to indicate that
-all registers except the stack pointer should be saved in the prologue
-regardless of whether they are used or not.
-@end table
+On MIPS targets, you can use the @code{micromips} and @code{nomicromips}
+function attributes to locally select or turn off microMIPS code generation.
+A function with the @code{micromips} attribute is emitted as microMIPS code,
+while microMIPS code generation is disabled for functions with the
+@code{nomicromips} attribute. These attributes override the
+@option{-mmicromips} and @option{-mno-micromips} options on the command line
+(@pxref{MIPS Options}).
-@node IA-64 Function Attributes
-@subsection IA-64 Function Attributes
+When compiling files containing mixed microMIPS and non-microMIPS code, the
+preprocessor symbol @code{__mips_micromips} reflects the setting on the
+command line,
+not that within individual functions. Mixed microMIPS and non-microMIPS code
+may interact badly with some GCC extensions such as @code{__builtin_apply}
+(@pxref{Constructing Calls}).
-These function attributes are supported on IA-64 targets:
+@cindex @code{nocompression} function attribute, MIPS
+@item nocompression
+On MIPS targets, you can use the @code{nocompression} function attribute
+to locally turn off MIPS16 and microMIPS code generation. This attribute
+overrides the @option{-mips16} and @option{-mmicromips} options on the
+command line (@pxref{MIPS Options}).
-@table @code
-@cindex @code{syscall_linkage} function attribute, IA-64
-@item syscall_linkage
-This attribute is used to modify the IA-64 calling convention by marking
-all input registers as live at all function exits. This makes it possible
-to restart a system call after an interrupt without having to save/restore
-the input registers. This also prevents kernel data from leaking into
-application code.
+@cindex @code{use_hazard_barrier_return} function attribute, MIPS
+@item use_hazard_barrier_return
+This function attribute instructs the compiler to generate a hazard barrier
+return that clears all execution and instruction hazards while returning,
+instead of generating a normal return instruction.
-@cindex @code{version_id} function attribute, IA-64
-@item version_id
-This IA-64 HP-UX attribute, attached to a global variable or function, renames a
-symbol to contain a version string, thus allowing for function level
-versioning. HP-UX system header files may use function level versioning
-for some system calls.
+@item code_readable
+@cindex @code{code_readable} function attribute, MIPS
+For MIPS targets that support PC-relative addressing modes, this attribute
+can be used to control how an object is addressed. The attribute takes
+a single optional argument:
-@smallexample
-extern int foo () __attribute__((version_id ("20040821")));
-@end smallexample
+@table @samp
+@item no
+The function should not read the instruction stream as data.
+@item yes
+The function can read the instruction stream as data.
+@item pcrel
+The function can read the instruction stream in a pc-relative mode.
+@end table
-@noindent
-Calls to @code{foo} are mapped to calls to @code{foo@{20040821@}}.
+If there is no argument supplied, the default of @code{"yes"} applies.
@end table
-@node LoongArch Function Attributes
-@subsection LoongArch Function Attributes
+@node MSP430 Function Attributes
+@subsection MSP430 Function Attributes
-These function attributes are supported by the LoongArch end:
+These function attributes are supported by the MSP430 back end:
@table @code
-@cindex @code{strict-align} function attribute, LoongArch
-@item strict-align
-@itemx no-strict-align
-@code{strict-align} indicates that the compiler should not assume that unaligned
-memory references are handled by the system. To allow the compiler to assume
-that aligned memory references are handled by the system, the inverse attribute
-@code{no-strict-align} can be specified. The behavior is same as for the
-command-line option @option{-mstrict-align} and @option{-mno-strict-align}.
+@cindex @code{critical} function attribute, MSP430
+@item critical
+Critical functions disable interrupts upon entry and restore the
+previous interrupt state upon exit. Critical functions cannot also
+have the @code{naked}, @code{reentrant} or @code{interrupt} attributes.
-@cindex @code{cmodel=} function attribute, LoongArch
-@item cmodel=
-Indicates that code should be generated for a particular code model for
-this function. The behavior and permissible arguments are the same as
-for the command-line option @option{-mcmodel=}.
+The MSP430 hardware ensures that interrupts are disabled on entry to
+@code{interrupt} functions, and restores the previous interrupt state
+on exit. The @code{critical} attribute is therefore redundant on
+@code{interrupt} functions.
-@cindex @code{arch=} function attribute, LoongArch
-@item arch=
-Specifies the architecture version and architectural extensions to use
-for this function. The behavior and permissible arguments are the same as
-for the @option{-march=} command-line option.
+@cindex @code{interrupt} function attribute, MSP430
+@item interrupt
+Use this attribute to indicate
+that the specified function is an interrupt handler. The compiler generates
+function entry and exit sequences suitable for use in an interrupt handler
+when this attribute is present.
-@cindex @code{tune=} function attribute, LoongArch
-@item tune=
-Specifies the core for which to tune the performance of this function.
-The behavior and permissible arguments are the same as for the @option{-mtune=}
-command-line option.
-
-@cindex @code{lsx} function attribute, LoongArch
-@item lsx
-@itemx no-lsx
-@code{lsx} indicates that vector instruction generation is allowed (not allowed)
-when compiling the function. The behavior is same as for the command-line option
-@option{-mlsx} and @option{-mno-lsx}.
-
-@cindex @code{lasx} function attribute, LoongArch
-@item lasx
-@itemx no-lasx
-@code{lasx} indicates that lasx instruction generation is allowed (not allowed)
-when compiling the function. The behavior is slightly different from the
-command-line option @option{-mno-lasx}.
-Example:
-
-@smallexample
-test.c:
-typedef int v4i32 __attribute__ ((vector_size(16), aligned(16)));
-
-v4i32 a, b, c;
-#ifdef WITH_ATTR
-__attribute__ ((target("no-lasx"))) void
-#else
-void
-#endif
-test ()
-@{
- c = a + b;
-@}
-@end smallexample
-@smallexample
-$ gcc test.c -o test.s -O2 -mlasx -DWITH_ATTR
-@end smallexample
-Compiled as above, 128-bit vectorization is possible.
-But the following method cannot perform 128-bit vectorization.
-@smallexample
-$ gcc test.c -o test.s -O2 -mlasx -mno-lasx
-@end smallexample
-
-@end table
-
-@node M32C Function Attributes
-@subsection M32C Function Attributes
-
-These function attributes are supported by the M32C back end:
-
-@table @code
-@cindex @code{bank_switch} function attribute, M32C
-@item bank_switch
-When added to an interrupt handler with the M32C port, causes the
-prologue and epilogue to use bank switching to preserve the registers
-rather than saving them on the stack.
-
-@cindex @code{fast_interrupt} function attribute, M32C
-@item fast_interrupt
-Use this attribute on the M32C port to indicate that the specified
-function is a fast interrupt handler. This is just like the
-@code{interrupt} attribute, except that @code{freit} is used to return
-instead of @code{reit}.
-
-@cindex @code{function_vector} function attribute, M16C/M32C
-@item function_vector
-On M16C/M32C targets, the @code{function_vector} attribute declares a
-special page subroutine call function. Use of this attribute reduces
-the code size by 2 bytes for each call generated to the
-subroutine. The argument to the attribute is the vector number entry
-from the special page vector table which contains the 16 low-order
-bits of the subroutine's entry address. Each vector table has special
-page number (18 to 255) that is used in @code{jsrs} instructions.
-Jump addresses of the routines are generated by adding 0x0F0000 (in
-case of M16C targets) or 0xFF0000 (in case of M32C targets), to the
-2-byte addresses set in the vector table. Therefore you need to ensure
-that all the special page vector routines should get mapped within the
-address range 0x0F0000 to 0x0FFFFF (for M16C) and 0xFF0000 to 0xFFFFFF
-(for M32C).
+You can provide an argument to the interrupt
+attribute which specifies a name or number. If the argument is a
+number it indicates the slot in the interrupt vector table (0 - 31) to
+which this handler should be assigned. If the argument is a name it
+is treated as a symbolic name for the vector slot. These names should
+match up with appropriate entries in the linker script. By default
+the names @code{watchdog} for vector 26, @code{nmi} for vector 30 and
+@code{reset} for vector 31 are recognized.
-In the following example 2 bytes are saved for each call to
-function @code{foo}.
+@cindex @code{naked} function attribute, MSP430
+@item naked
+This attribute allows the compiler to construct the
+requisite function declaration, while allowing the body of the
+function to be assembly code. The specified function will not have
+prologue/epilogue sequences generated by the compiler. Only basic
+@code{asm} statements can safely be included in naked functions
+(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
+basic @code{asm} and C code may appear to work, they cannot be
+depended upon to work reliably and are not supported.
-@smallexample
-void foo (void) __attribute__((function_vector(0x18)));
-void foo (void)
-@{
-@}
+@cindex @code{reentrant} function attribute, MSP430
+@item reentrant
+Reentrant functions disable interrupts upon entry and enable them
+upon exit. Reentrant functions cannot also have the @code{naked}
+or @code{critical} attributes. They can have the @code{interrupt}
+attribute.
-void bar (void)
-@{
- foo();
-@}
-@end smallexample
+@cindex @code{wakeup} function attribute, MSP430
+@item wakeup
+This attribute only applies to interrupt functions. It is silently
+ignored if applied to a non-interrupt function. A wakeup interrupt
+function will rouse the processor from any low-power state that it
+might be in when the function exits.
-If functions are defined in one file and are called in another file,
-then be sure to write this declaration in both files.
+@cindex @code{lower} function attribute, MSP430
+@cindex @code{upper} function attribute, MSP430
+@cindex @code{either} function attribute, MSP430
+@item lower
+@itemx upper
+@itemx either
+On the MSP430 target these attributes can be used to specify whether
+the function or variable should be placed into low memory, high
+memory, or the placement should be left to the linker to decide. The
+attributes are only significant if compiling for the MSP430X
+architecture in the large memory model.
-This attribute is ignored for R8C target.
+The attributes work in conjunction with a linker script that has been
+augmented to specify where to place sections with a @code{.lower} and
+a @code{.upper} prefix. So, for example, as well as placing the
+@code{.data} section, the script also specifies the placement of a
+@code{.lower.data} and a @code{.upper.data} section. The intention
+is that @code{lower} sections are placed into a small but easier to
+access memory region and the upper sections are placed into a larger, but
+slower to access, region.
-@cindex @code{interrupt} function attribute, M32C
-@item interrupt
-Use this attribute to indicate
-that the specified function is an interrupt handler. The compiler generates
-function entry and exit sequences suitable for use in an interrupt handler
-when this attribute is present.
+The @code{either} attribute is special. It tells the linker to place
+the object into the corresponding @code{lower} section if there is
+room for it. If there is insufficient room then the object is placed
+into the corresponding @code{upper} section instead. Note that the
+placement algorithm is not very sophisticated. It does not attempt to
+find an optimal packing of the @code{lower} sections. It just makes
+one pass over the objects and does the best that it can. Using the
+@option{-ffunction-sections} and @option{-fdata-sections} command-line
+options can help the packing, however, since they produce smaller,
+easier to pack regions.
@end table
-@node M32R/D Function Attributes
-@subsection M32R/D Function Attributes
+@node NDS32 Function Attributes
+@subsection NDS32 Function Attributes
-These function attributes are supported by the M32R/D back end:
+These function attributes are supported by the NDS32 back end:
@table @code
-@cindex @code{interrupt} function attribute, M32R/D
-@item interrupt
-Use this attribute to indicate
-that the specified function is an interrupt handler. The compiler generates
-function entry and exit sequences suitable for use in an interrupt handler
-when this attribute is present.
-
-@cindex @code{model} function attribute, M32R/D
-@cindex function addressability on the M32R/D
-@item model (@var{model-name})
-
-On the M32R/D, use this attribute to set the addressability of an
-object, and of the code generated for a function. The identifier
-@var{model-name} is one of @code{small}, @code{medium}, or
-@code{large}, representing each of the code models.
-
-Small model objects live in the lower 16MB of memory (so that their
-addresses can be loaded with the @code{ld24} instruction), and are
-callable with the @code{bl} instruction.
-
-Medium model objects may live anywhere in the 32-bit address space (the
-compiler generates @code{seth/add3} instructions to load their addresses),
-and are callable with the @code{bl} instruction.
-
-Large model objects may live anywhere in the 32-bit address space (the
-compiler generates @code{seth/add3} instructions to load their addresses),
-and may not be reachable with the @code{bl} instruction (the compiler
-generates the much slower @code{seth/add3/jl} instruction sequence).
-@end table
-
-@node m68k Function Attributes
-@subsection m68k Function Attributes
-
-These function attributes are supported by the m68k back end:
+@cindex @code{exception} function attribute
+@cindex exception handler functions, NDS32
+@item exception
+Use this attribute on the NDS32 target to indicate that the specified function
+is an exception handler. The compiler will generate corresponding sections
+for use in an exception handler.
-@table @code
-@cindex @code{interrupt} function attribute, m68k
-@cindex @code{interrupt_handler} function attribute, m68k
+@cindex @code{interrupt} function attribute, NDS32
@item interrupt
-@itemx interrupt_handler
-Use this attribute to
-indicate that the specified function is an interrupt handler. The compiler
-generates function entry and exit sequences suitable for use in an
-interrupt handler when this attribute is present. Either name may be used.
-
-@cindex @code{interrupt_thread} function attribute, fido
-@item interrupt_thread
-Use this attribute on fido, a subarchitecture of the m68k, to indicate
-that the specified function is an interrupt handler that is designed
-to run as a thread. The compiler omits generate prologue/epilogue
-sequences and replaces the return instruction with a @code{sleep}
-instruction. This attribute is available only on fido.
+On NDS32 target, this attribute indicates that the specified function
+is an interrupt handler. The compiler generates corresponding sections
+for use in an interrupt handler. You can use the following attributes
+to modify the behavior:
+@table @code
+@cindex @code{nested} function attribute, NDS32
+@item nested
+This interrupt service routine is interruptible.
+@cindex @code{not_nested} function attribute, NDS32
+@item not_nested
+This interrupt service routine is not interruptible.
+@cindex @code{nested_ready} function attribute, NDS32
+@item nested_ready
+This interrupt service routine is interruptible after @code{PSW.GIE}
+(global interrupt enable) is set. This allows interrupt service routine to
+finish some short critical code before enabling interrupts.
+@cindex @code{save_all} function attribute, NDS32
+@item save_all
+The system will help save all registers into stack before entering
+interrupt handler.
+@cindex @code{partial_save} function attribute, NDS32
+@item partial_save
+The system will help save caller registers into stack before entering
+interrupt handler.
@end table
-@node MCORE Function Attributes
-@subsection MCORE Function Attributes
-
-These function attributes are supported by the MCORE back end:
-
-@table @code
-@cindex @code{naked} function attribute, MCORE
+@cindex @code{naked} function attribute, NDS32
@item naked
This attribute allows the compiler to construct the
requisite function declaration, while allowing the body of the
(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
basic @code{asm} and C code may appear to work, they cannot be
depended upon to work reliably and are not supported.
-@end table
-
-@node MicroBlaze Function Attributes
-@subsection MicroBlaze Function Attributes
-
-These function attributes are supported on MicroBlaze targets:
+@cindex @code{reset} function attribute, NDS32
+@cindex reset handler functions
+@item reset
+Use this attribute on the NDS32 target to indicate that the specified function
+is a reset handler. The compiler will generate corresponding sections
+for use in a reset handler. You can use the following attributes
+to provide extra exception handling:
@table @code
-@cindex @code{save_volatiles} function attribute, MicroBlaze
-@item save_volatiles
-Use this attribute to indicate that the function is
-an interrupt handler. All volatile registers (in addition to non-volatile
-registers) are saved in the function prologue. If the function is a leaf
-function, only volatiles used by the function are saved. A normal function
-return is generated instead of a return from interrupt.
+@cindex @code{nmi} function attribute, NDS32
+@item nmi
+Provide a user-defined function to handle NMI exception.
+@cindex @code{warm} function attribute, NDS32
+@item warm
+Provide a user-defined function to handle warm reset exception.
+@end table
+@end table
-@cindex @code{break_handler} function attribute, MicroBlaze
-@cindex break handler functions
-@item break_handler
-Use this attribute to indicate that
-the specified function is a break handler. The compiler generates function
-entry and exit sequences suitable for use in an break handler when this
-attribute is present. The return from @code{break_handler} is done through
-the @code{rtbd} instead of @code{rtsd}.
+@node Nvidia PTX Function Attributes
+@subsection Nvidia PTX Function Attributes
-@smallexample
-void f () __attribute__ ((break_handler));
-@end smallexample
+These function attributes are supported by the Nvidia PTX back end:
-@cindex @code{interrupt_handler} function attribute, MicroBlaze
-@cindex @code{fast_interrupt} function attribute, MicroBlaze
-@item interrupt_handler
-@itemx fast_interrupt
-These attributes indicate that the specified function is an interrupt
-handler. Use the @code{fast_interrupt} attribute to indicate handlers
-used in low-latency interrupt mode, and @code{interrupt_handler} for
-interrupts that do not use low-latency handlers. In both cases, GCC
-emits appropriate prologue code and generates a return from the handler
-using @code{rtid} instead of @code{rtsd}.
+@table @code
+@cindex @code{kernel} function attribute, Nvidia PTX
+@item kernel
+This attribute indicates that the corresponding function should be compiled
+as a kernel function, which can be invoked from the host via the CUDA RT
+library.
+By default functions are only callable only from other PTX functions.
+
+Kernel functions must have @code{void} return type.
@end table
-@node Microsoft Windows Function Attributes
-@subsection Microsoft Windows Function Attributes
+@node PowerPC Function Attributes
+@subsection PowerPC Function Attributes
-The following attributes are available on Microsoft Windows and Symbian OS
-targets.
+These function attributes are supported by the PowerPC back end:
@table @code
-@cindex @code{dllexport} function attribute
-@cindex @code{__declspec(dllexport)}
-@item dllexport
-On Microsoft Windows targets and Symbian OS targets the
-@code{dllexport} attribute causes the compiler to provide a global
-pointer to a pointer in a DLL, so that it can be referenced with the
-@code{dllimport} attribute. On Microsoft Windows targets, the pointer
-name is formed by combining @code{_imp__} and the function or variable
-name.
-
-You can use @code{__declspec(dllexport)} as a synonym for
-@code{__attribute__ ((dllexport))} for compatibility with other
-compilers.
+@cindex indirect calls, PowerPC
+@cindex @code{longcall} function attribute, PowerPC
+@cindex @code{shortcall} function attribute, PowerPC
+@item longcall
+@itemx shortcall
+The @code{longcall} attribute
+indicates that the function might be far away from the call site and
+require a different (more expensive) calling sequence. The
+@code{shortcall} attribute indicates that the function is always close
+enough for the shorter calling sequence to be used. These attributes
+override both the @option{-mlongcall} switch and
+the @code{#pragma longcall} setting.
-On systems that support the @code{visibility} attribute, this
-attribute also implies ``default'' visibility. It is an error to
-explicitly specify any other visibility.
+@xref{RS/6000 and PowerPC Options}, for more information on whether long
+calls are necessary.
-GCC's default behavior is to emit all inline functions with the
-@code{dllexport} attribute. Since this can cause object file-size bloat,
-you can use @option{-fno-keep-inline-dllexport}, which tells GCC to
-ignore the attribute for inlined functions unless the
-@option{-fkeep-inline-functions} flag is used instead.
+@cindex @code{target} function attribute
+@item target (@var{options})
+As discussed in @ref{Common Function Attributes}, this attribute
+allows specification of target-specific compilation options.
-The attribute is ignored for undefined symbols.
+On the PowerPC, the following options are allowed:
-When applied to C++ classes, the attribute marks defined non-inlined
-member functions and static data members as exports. Static consts
-initialized in-class are not marked unless they are also defined
-out-of-class.
+@table @samp
+@cindex @code{target("altivec")} function attribute, PowerPC
+@item altivec
+@itemx no-altivec
+Generate code that uses (does not use) AltiVec instructions. In
+32-bit code, you cannot enable AltiVec instructions unless
+@option{-mabi=altivec} is used on the command line.
-For Microsoft Windows targets there are alternative methods for
-including the symbol in the DLL's export table such as using a
-@file{.def} file with an @code{EXPORTS} section or, with GNU ld, using
-the @option{--export-all} linker flag.
+@cindex @code{target("cmpb")} function attribute, PowerPC
+@item cmpb
+@itemx no-cmpb
+Generate code that uses (does not use) the compare bytes instruction
+implemented on the POWER6 processor and other processors that support
+the PowerPC V2.05 architecture.
-@cindex @code{dllimport} function attribute
-@cindex @code{__declspec(dllimport)}
-@item dllimport
-On Microsoft Windows and Symbian OS targets, the @code{dllimport}
-attribute causes the compiler to reference a function or variable via
-a global pointer to a pointer that is set up by the DLL exporting the
-symbol. The attribute implies @code{extern}. On Microsoft Windows
-targets, the pointer name is formed by combining @code{_imp__} and the
-function or variable name.
+@cindex @code{target("dlmzb")} function attribute, PowerPC
+@item dlmzb
+@itemx no-dlmzb
+Generate code that uses (does not use) the string-search @samp{dlmzb}
+instruction on the IBM 405, 440, 464 and 476 processors. This instruction is
+generated by default when targeting those processors.
-You can use @code{__declspec(dllimport)} as a synonym for
-@code{__attribute__ ((dllimport))} for compatibility with other
-compilers.
+@cindex @code{target("fprnd")} function attribute, PowerPC
+@item fprnd
+@itemx no-fprnd
+Generate code that uses (does not use) the FP round to integer
+instructions implemented on the POWER5+ processor and other processors
+that support the PowerPC V2.03 architecture.
-On systems that support the @code{visibility} attribute, this
-attribute also implies ``default'' visibility. It is an error to
-explicitly specify any other visibility.
+@cindex @code{target("hard-dfp")} function attribute, PowerPC
+@item hard-dfp
+@itemx no-hard-dfp
+Generate code that uses (does not use) the decimal floating-point
+instructions implemented on some POWER processors.
-Currently, the attribute is ignored for inlined functions. If the
-attribute is applied to a symbol @emph{definition}, an error is reported.
-If a symbol previously declared @code{dllimport} is later defined, the
-attribute is ignored in subsequent references, and a warning is emitted.
-The attribute is also overridden by a subsequent declaration as
-@code{dllexport}.
+@cindex @code{target("isel")} function attribute, PowerPC
+@item isel
+@itemx no-isel
+Generate code that uses (does not use) ISEL instruction.
-When applied to C++ classes, the attribute marks non-inlined
-member functions and static data members as imports. However, the
-attribute is ignored for virtual methods to allow creation of vtables
-using thunks.
+@cindex @code{target("mfcrf")} function attribute, PowerPC
+@item mfcrf
+@itemx no-mfcrf
+Generate code that uses (does not use) the move from condition
+register field instruction implemented on the POWER4 processor and
+other processors that support the PowerPC V2.01 architecture.
-On the SH Symbian OS target the @code{dllimport} attribute also has
-another affect---it can cause the vtable and run-time type information
-for a class to be exported. This happens when the class has a
-dllimported constructor or a non-inline, non-pure virtual function
-and, for either of those two conditions, the class also has an inline
-constructor or destructor and has a key function that is defined in
-the current translation unit.
+@cindex @code{target("mulhw")} function attribute, PowerPC
+@item mulhw
+@itemx no-mulhw
+Generate code that uses (does not use) the half-word multiply and
+multiply-accumulate instructions on the IBM 405, 440, 464 and 476 processors.
+These instructions are generated by default when targeting those
+processors.
-For Microsoft Windows targets the use of the @code{dllimport}
-attribute on functions is not necessary, but provides a small
-performance benefit by eliminating a thunk in the DLL@. The use of the
-@code{dllimport} attribute on imported variables can be avoided by passing the
-@option{--enable-auto-import} switch to the GNU linker. As with
-functions, using the attribute for a variable eliminates a thunk in
-the DLL@.
+@cindex @code{target("multiple")} function attribute, PowerPC
+@item multiple
+@itemx no-multiple
+Generate code that uses (does not use) the load multiple word
+instructions and the store multiple word instructions.
-One drawback to using this attribute is that a pointer to a
-@emph{variable} marked as @code{dllimport} cannot be used as a constant
-address. However, a pointer to a @emph{function} with the
-@code{dllimport} attribute can be used as a constant initializer; in
-this case, the address of a stub function in the import lib is
-referenced. On Microsoft Windows targets, the attribute can be disabled
-for functions by setting the @option{-mnop-fun-dllimport} flag.
-@end table
+@cindex @code{target("update")} function attribute, PowerPC
+@item update
+@itemx no-update
+Generate code that uses (does not use) the load or store instructions
+that update the base register to the address of the calculated memory
+location.
-@node MIPS Function Attributes
-@subsection MIPS Function Attributes
+@cindex @code{target("popcntb")} function attribute, PowerPC
+@item popcntb
+@itemx no-popcntb
+Generate code that uses (does not use) the popcount and double-precision
+FP reciprocal estimate instruction implemented on the POWER5
+processor and other processors that support the PowerPC V2.02
+architecture.
-These function attributes are supported by the MIPS back end:
+@cindex @code{target("popcntd")} function attribute, PowerPC
+@item popcntd
+@itemx no-popcntd
+Generate code that uses (does not use) the popcount instruction
+implemented on the POWER7 processor and other processors that support
+the PowerPC V2.06 architecture.
-@table @code
-@cindex @code{interrupt} function attribute, MIPS
-@item interrupt
-Use this attribute to indicate that the specified function is an interrupt
-handler. The compiler generates function entry and exit sequences suitable
-for use in an interrupt handler when this attribute is present.
-An optional argument is supported for the interrupt attribute which allows
-the interrupt mode to be described. By default GCC assumes the external
-interrupt controller (EIC) mode is in use, this can be explicitly set using
-@code{eic}. When interrupts are non-masked then the requested Interrupt
-Priority Level (IPL) is copied to the current IPL which has the effect of only
-enabling higher priority interrupts. To use vectored interrupt mode use
-the argument @code{vector=[sw0|sw1|hw0|hw1|hw2|hw3|hw4|hw5]}, this will change
-the behavior of the non-masked interrupt support and GCC will arrange to mask
-all interrupts from sw0 up to and including the specified interrupt vector.
+@cindex @code{target("powerpc-gfxopt")} function attribute, PowerPC
+@item powerpc-gfxopt
+@itemx no-powerpc-gfxopt
+Generate code that uses (does not use) the optional PowerPC
+architecture instructions in the Graphics group, including
+floating-point select.
-You can use the following attributes to modify the behavior
-of an interrupt handler:
-@table @code
-@cindex @code{use_shadow_register_set} function attribute, MIPS
-@item use_shadow_register_set
-Assume that the handler uses a shadow register set, instead of
-the main general-purpose registers. An optional argument @code{intstack} is
-supported to indicate that the shadow register set contains a valid stack
-pointer.
-
-@cindex @code{keep_interrupts_masked} function attribute, MIPS
-@item keep_interrupts_masked
-Keep interrupts masked for the whole function. Without this attribute,
-GCC tries to reenable interrupts for as much of the function as it can.
-
-@cindex @code{use_debug_exception_return} function attribute, MIPS
-@item use_debug_exception_return
-Return using the @code{deret} instruction. Interrupt handlers that don't
-have this attribute return using @code{eret} instead.
-@end table
-
-You can use any combination of these attributes, as shown below:
-@smallexample
-void __attribute__ ((interrupt)) v0 ();
-void __attribute__ ((interrupt, use_shadow_register_set)) v1 ();
-void __attribute__ ((interrupt, keep_interrupts_masked)) v2 ();
-void __attribute__ ((interrupt, use_debug_exception_return)) v3 ();
-void __attribute__ ((interrupt, use_shadow_register_set,
- keep_interrupts_masked)) v4 ();
-void __attribute__ ((interrupt, use_shadow_register_set,
- use_debug_exception_return)) v5 ();
-void __attribute__ ((interrupt, keep_interrupts_masked,
- use_debug_exception_return)) v6 ();
-void __attribute__ ((interrupt, use_shadow_register_set,
- keep_interrupts_masked,
- use_debug_exception_return)) v7 ();
-void __attribute__ ((interrupt("eic"))) v8 ();
-void __attribute__ ((interrupt("vector=hw3"))) v9 ();
-@end smallexample
-
-@cindex indirect calls, MIPS
-@cindex @code{long_call} function attribute, MIPS
-@cindex @code{short_call} function attribute, MIPS
-@cindex @code{near} function attribute, MIPS
-@cindex @code{far} function attribute, MIPS
-@item long_call
-@itemx short_call
-@itemx near
-@itemx far
-These attributes specify how a particular function is called on MIPS@.
-The attributes override the @option{-mlong-calls} (@pxref{MIPS Options})
-command-line switch. The @code{long_call} and @code{far} attributes are
-synonyms, and cause the compiler to always call
-the function by first loading its address into a register, and then using
-the contents of that register. The @code{short_call} and @code{near}
-attributes are synonyms, and have the opposite
-effect; they specify that non-PIC calls should be made using the more
-efficient @code{jal} instruction.
-
-@cindex @code{mips16} function attribute, MIPS
-@cindex @code{nomips16} function attribute, MIPS
-@item mips16
-@itemx nomips16
+@cindex @code{target("powerpc-gpopt")} function attribute, PowerPC
+@item powerpc-gpopt
+@itemx no-powerpc-gpopt
+Generate code that uses (does not use) the optional PowerPC
+architecture instructions in the General Purpose group, including
+floating-point square root.
-On MIPS targets, you can use the @code{mips16} and @code{nomips16}
-function attributes to locally select or turn off MIPS16 code generation.
-A function with the @code{mips16} attribute is emitted as MIPS16 code,
-while MIPS16 code generation is disabled for functions with the
-@code{nomips16} attribute. These attributes override the
-@option{-mips16} and @option{-mno-mips16} options on the command line
-(@pxref{MIPS Options}).
+@cindex @code{target("recip-precision")} function attribute, PowerPC
+@item recip-precision
+@itemx no-recip-precision
+Assume (do not assume) that the reciprocal estimate instructions
+provide higher-precision estimates than is mandated by the PowerPC
+ABI.
-When compiling files containing mixed MIPS16 and non-MIPS16 code, the
-preprocessor symbol @code{__mips16} reflects the setting on the command line,
-not that within individual functions. Mixed MIPS16 and non-MIPS16 code
-may interact badly with some GCC extensions such as @code{__builtin_apply}
-(@pxref{Constructing Calls}).
+@cindex @code{target("string")} function attribute, PowerPC
+@item string
+@itemx no-string
+Generate code that uses (does not use) the load string instructions
+and the store string word instructions to save multiple registers and
+do small block moves.
-@cindex @code{micromips} function attribute
-@cindex @code{nomicromips} function attribute
-@item micromips, MIPS
-@itemx nomicromips, MIPS
+@cindex @code{target("vsx")} function attribute, PowerPC
+@item vsx
+@itemx no-vsx
+Generate code that uses (does not use) vector/scalar (VSX)
+instructions, and also enable the use of built-in functions that allow
+more direct access to the VSX instruction set. In 32-bit code, you
+cannot enable VSX or AltiVec instructions unless
+@option{-mabi=altivec} is used on the command line.
-On MIPS targets, you can use the @code{micromips} and @code{nomicromips}
-function attributes to locally select or turn off microMIPS code generation.
-A function with the @code{micromips} attribute is emitted as microMIPS code,
-while microMIPS code generation is disabled for functions with the
-@code{nomicromips} attribute. These attributes override the
-@option{-mmicromips} and @option{-mno-micromips} options on the command line
-(@pxref{MIPS Options}).
+@cindex @code{target("friz")} function attribute, PowerPC
+@item friz
+@itemx no-friz
+Generate (do not generate) the @code{friz} instruction when the
+@option{-funsafe-math-optimizations} option is used to optimize
+rounding a floating-point value to 64-bit integer and back to floating
+point. The @code{friz} instruction does not return the same value if
+the floating-point number is too large to fit in an integer.
-When compiling files containing mixed microMIPS and non-microMIPS code, the
-preprocessor symbol @code{__mips_micromips} reflects the setting on the
-command line,
-not that within individual functions. Mixed microMIPS and non-microMIPS code
-may interact badly with some GCC extensions such as @code{__builtin_apply}
-(@pxref{Constructing Calls}).
+@cindex @code{target("avoid-indexed-addresses")} function attribute, PowerPC
+@item avoid-indexed-addresses
+@itemx no-avoid-indexed-addresses
+Generate code that tries to avoid (not avoid) the use of indexed load
+or store instructions.
-@cindex @code{nocompression} function attribute, MIPS
-@item nocompression
-On MIPS targets, you can use the @code{nocompression} function attribute
-to locally turn off MIPS16 and microMIPS code generation. This attribute
-overrides the @option{-mips16} and @option{-mmicromips} options on the
-command line (@pxref{MIPS Options}).
+@cindex @code{target("paired")} function attribute, PowerPC
+@item paired
+@itemx no-paired
+Generate code that uses (does not use) the generation of PAIRED simd
+instructions.
-@cindex @code{use_hazard_barrier_return} function attribute, MIPS
-@item use_hazard_barrier_return
-This function attribute instructs the compiler to generate a hazard barrier
-return that clears all execution and instruction hazards while returning,
-instead of generating a normal return instruction.
+@cindex @code{target("longcall")} function attribute, PowerPC
+@item longcall
+@itemx no-longcall
+Generate code that assumes (does not assume) that all calls are far
+away so that a longer more expensive calling sequence is required.
-@item code_readable
-@cindex @code{code_readable} function attribute, MIPS
-For MIPS targets that support PC-relative addressing modes, this attribute
-can be used to control how an object is addressed. The attribute takes
-a single optional argument:
+@cindex @code{target("cpu=@var{CPU}")} function attribute, PowerPC
+@item cpu=@var{CPU}
+Specify the architecture to generate code for when compiling the
+function. If you select the @code{target("cpu=power7")} attribute when
+generating 32-bit code, VSX and AltiVec instructions are not generated
+unless you use the @option{-mabi=altivec} option on the command line.
-@table @samp
-@item no
-The function should not read the instruction stream as data.
-@item yes
-The function can read the instruction stream as data.
-@item pcrel
-The function can read the instruction stream in a pc-relative mode.
+@cindex @code{target("tune=@var{TUNE}")} function attribute, PowerPC
+@item tune=@var{TUNE}
+Specify the architecture to tune for when compiling the function. If
+you do not specify the @code{target("tune=@var{TUNE}")} attribute and
+you do specify the @code{target("cpu=@var{CPU}")} attribute,
+compilation tunes for the @var{CPU} architecture, and not the
+default tuning specified on the command line.
@end table
-If there is no argument supplied, the default of @code{"yes"} applies.
+On the PowerPC, 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.
@end table
-@node MSP430 Function Attributes
-@subsection MSP430 Function Attributes
+@node RISC-V Function Attributes
+@subsection RISC-V Function Attributes
-These function attributes are supported by the MSP430 back end:
+These function attributes are supported by the RISC-V back end:
@table @code
-@cindex @code{critical} function attribute, MSP430
-@item critical
-Critical functions disable interrupts upon entry and restore the
-previous interrupt state upon exit. Critical functions cannot also
-have the @code{naked}, @code{reentrant} or @code{interrupt} attributes.
-
-The MSP430 hardware ensures that interrupts are disabled on entry to
-@code{interrupt} functions, and restores the previous interrupt state
-on exit. The @code{critical} attribute is therefore redundant on
-@code{interrupt} functions.
-
-@cindex @code{interrupt} function attribute, MSP430
-@item interrupt
-Use this attribute to indicate
-that the specified function is an interrupt handler. The compiler generates
-function entry and exit sequences suitable for use in an interrupt handler
-when this attribute is present.
-
-You can provide an argument to the interrupt
-attribute which specifies a name or number. If the argument is a
-number it indicates the slot in the interrupt vector table (0 - 31) to
-which this handler should be assigned. If the argument is a name it
-is treated as a symbolic name for the vector slot. These names should
-match up with appropriate entries in the linker script. By default
-the names @code{watchdog} for vector 26, @code{nmi} for vector 30 and
-@code{reset} for vector 31 are recognized.
-
-@cindex @code{naked} function attribute, MSP430
+@cindex @code{naked} function attribute, RISC-V
@item naked
This attribute allows the compiler to construct the
requisite function declaration, while allowing the body of the
basic @code{asm} and C code may appear to work, they cannot be
depended upon to work reliably and are not supported.
-@cindex @code{reentrant} function attribute, MSP430
-@item reentrant
-Reentrant functions disable interrupts upon entry and enable them
-upon exit. Reentrant functions cannot also have the @code{naked}
-or @code{critical} attributes. They can have the @code{interrupt}
-attribute.
+@cindex @code{interrupt} function attribute, RISC-V
+@item interrupt
+Use this attribute to indicate that the specified function is an interrupt
+handler. The compiler generates function entry and exit sequences suitable
+for use in an interrupt handler when this attribute is present.
-@cindex @code{wakeup} function attribute, MSP430
-@item wakeup
-This attribute only applies to interrupt functions. It is silently
-ignored if applied to a non-interrupt function. A wakeup interrupt
-function will rouse the processor from any low-power state that it
-might be in when the function exits.
+You can specify the kind of interrupt to be handled by adding an optional
+parameter to the interrupt attribute like this:
-@cindex @code{lower} function attribute, MSP430
-@cindex @code{upper} function attribute, MSP430
-@cindex @code{either} function attribute, MSP430
-@item lower
-@itemx upper
-@itemx either
-On the MSP430 target these attributes can be used to specify whether
-the function or variable should be placed into low memory, high
-memory, or the placement should be left to the linker to decide. The
-attributes are only significant if compiling for the MSP430X
-architecture in the large memory model.
+@smallexample
+void f (void) __attribute__ ((interrupt ("user")));
+@end smallexample
-The attributes work in conjunction with a linker script that has been
-augmented to specify where to place sections with a @code{.lower} and
-a @code{.upper} prefix. So, for example, as well as placing the
-@code{.data} section, the script also specifies the placement of a
-@code{.lower.data} and a @code{.upper.data} section. The intention
-is that @code{lower} sections are placed into a small but easier to
-access memory region and the upper sections are placed into a larger, but
-slower to access, region.
+Permissible values for this parameter are @code{user}, @code{supervisor},
+and @code{machine}. If there is no parameter, then it defaults to
+@code{machine}.
-The @code{either} attribute is special. It tells the linker to place
-the object into the corresponding @code{lower} section if there is
-room for it. If there is insufficient room then the object is placed
-into the corresponding @code{upper} section instead. Note that the
-placement algorithm is not very sophisticated. It does not attempt to
-find an optimal packing of the @code{lower} sections. It just makes
-one pass over the objects and does the best that it can. Using the
-@option{-ffunction-sections} and @option{-fdata-sections} command-line
-options can help the packing, however, since they produce smaller,
-easier to pack regions.
-@end table
+@cindex @code{riscv_vector_cc} function attribute, RISC-V
+@item riscv_vector_cc
+Use this attribute to force the function to use the vector calling
+convention variant.
-@node NDS32 Function Attributes
-@subsection NDS32 Function Attributes
+@smallexample
+void foo() __attribute__((riscv_vector_cc));
+[[riscv::vector_cc]] void foo(); // For C++11 and C23
+@end smallexample
-These function attributes are supported by the NDS32 back end:
+@end table
-@table @code
-@cindex @code{exception} function attribute
-@cindex exception handler functions, NDS32
-@item exception
-Use this attribute on the NDS32 target to indicate that the specified function
-is an exception handler. The compiler will generate corresponding sections
-for use in an exception handler.
+The following target-specific function attributes are available for the
+RISC-V target. For the most part, these options mirror the behavior of
+similar command-line options (@pxref{RISC-V Options}), but on a
+per-function basis.
-@cindex @code{interrupt} function attribute, NDS32
-@item interrupt
-On NDS32 target, this attribute indicates that the specified function
-is an interrupt handler. The compiler generates corresponding sections
-for use in an interrupt handler. You can use the following attributes
-to modify the behavior:
@table @code
-@cindex @code{nested} function attribute, NDS32
-@item nested
-This interrupt service routine is interruptible.
-@cindex @code{not_nested} function attribute, NDS32
-@item not_nested
-This interrupt service routine is not interruptible.
-@cindex @code{nested_ready} function attribute, NDS32
-@item nested_ready
-This interrupt service routine is interruptible after @code{PSW.GIE}
-(global interrupt enable) is set. This allows interrupt service routine to
-finish some short critical code before enabling interrupts.
-@cindex @code{save_all} function attribute, NDS32
-@item save_all
-The system will help save all registers into stack before entering
-interrupt handler.
-@cindex @code{partial_save} function attribute, NDS32
-@item partial_save
-The system will help save caller registers into stack before entering
-interrupt handler.
+@cindex @code{arch=} function attribute, RISC-V
+@item arch=
+Specifies the architecture version and architectural extensions to use
+for this function. The behavior and permissible arguments are the same as
+for the @option{-march=} command-line option, in addtion, it also support
+extension enablement list, a list of extension name and prefixed with @code{+},
+like @code{arch=+zba} means enable @code{zba} extension.
+Multiple extension can be enabled by separating them with a comma. For example:
+@code{arch=+zba,+zbb}.
+
+@cindex @code{tune=} function attribute, RISC-V
+@item tune=
+Specifies the core for which to tune the performance of this function.
+The behavior and permissible arguments are the same as for the @option{-mtune=}
+command-line option.
+
+@cindex @code{cpu=} function attribute, RISC-V
+@item cpu=
+Specifies the core for which to tune the performance of this function and also
+whose architectural features to use. The behavior and valid arguments are the
+same as for the @option{-mcpu=} command-line option.
+
@end table
-@cindex @code{naked} function attribute, NDS32
+The above target attributes can be specified as follows:
+
+@smallexample
+__attribute__((target("@var{attr-string}")))
+int
+f (int a)
+@{
+ return a + 5;
+@}
+@end smallexample
+
+where @code{@var{attr-string}} is one of the attribute strings specified above.
+
+Multiple target function attributes can be specified by separating them with
+a semicolon. For example:
+@smallexample
+__attribute__((target("arch=+zba,+zbb;tune=rocket")))
+int
+foo (int a)
+@{
+ return a + 5;
+@}
+@end smallexample
+
+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
+
+These function attributes are supported by the RL78 back end:
+
+@table @code
+@cindex @code{interrupt} function attribute, RL78
+@cindex @code{brk_interrupt} function attribute, RL78
+@item interrupt
+@itemx brk_interrupt
+These attributes indicate
+that the specified function is an interrupt handler. The compiler generates
+function entry and exit sequences suitable for use in an interrupt handler
+when this attribute is present.
+
+Use @code{brk_interrupt} instead of @code{interrupt} for
+handlers intended to be used with the @code{BRK} opcode (i.e.@: those
+that must end with @code{RETB} instead of @code{RETI}).
+
+@cindex @code{naked} function attribute, RL78
@item naked
This attribute allows the compiler to construct the
requisite function declaration, while allowing the body of the
(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
basic @code{asm} and C code may appear to work, they cannot be
depended upon to work reliably and are not supported.
-
-@cindex @code{reset} function attribute, NDS32
-@cindex reset handler functions
-@item reset
-Use this attribute on the NDS32 target to indicate that the specified function
-is a reset handler. The compiler will generate corresponding sections
-for use in a reset handler. You can use the following attributes
-to provide extra exception handling:
-@table @code
-@cindex @code{nmi} function attribute, NDS32
-@item nmi
-Provide a user-defined function to handle NMI exception.
-@cindex @code{warm} function attribute, NDS32
-@item warm
-Provide a user-defined function to handle warm reset exception.
-@end table
@end table
-@node Nvidia PTX Function Attributes
-@subsection Nvidia PTX Function Attributes
+@node RX Function Attributes
+@subsection RX Function Attributes
-These function attributes are supported by the Nvidia PTX back end:
+These function attributes are supported by the RX back end:
@table @code
-@cindex @code{kernel} function attribute, Nvidia PTX
-@item kernel
-This attribute indicates that the corresponding function should be compiled
-as a kernel function, which can be invoked from the host via the CUDA RT
-library.
-By default functions are only callable only from other PTX functions.
+@cindex @code{fast_interrupt} function attribute, RX
+@item fast_interrupt
+Use this attribute on the RX port to indicate that the specified
+function is a fast interrupt handler. This is just like the
+@code{interrupt} attribute, except that @code{freit} is used to return
+instead of @code{reit}.
-Kernel functions must have @code{void} return type.
+@cindex @code{interrupt} function attribute, RX
+@item interrupt
+Use this attribute to indicate
+that the specified function is an interrupt handler. The compiler generates
+function entry and exit sequences suitable for use in an interrupt handler
+when this attribute is present.
+
+On RX and RL78 targets, you may specify one or more vector numbers as arguments
+to the attribute, as well as naming an alternate table name.
+Parameters are handled sequentially, so one handler can be assigned to
+multiple entries in multiple tables. One may also pass the magic
+string @code{"$default"} which causes the function to be used for any
+unfilled slots in the current table.
+
+This example shows a simple assignment of a function to one vector in
+the default table (note that preprocessor macros may be used for
+chip-specific symbolic vector names):
+@smallexample
+void __attribute__ ((interrupt (5))) txd1_handler ();
+@end smallexample
+
+This example assigns a function to two slots in the default table
+(using preprocessor macros defined elsewhere) and makes it the default
+for the @code{dct} table:
+@smallexample
+void __attribute__ ((interrupt (RXD1_VECT,RXD2_VECT,"dct","$default")))
+ txd1_handler ();
+@end smallexample
+
+@cindex @code{naked} function attribute, RX
+@item naked
+This attribute allows the compiler to construct the
+requisite function declaration, while allowing the body of the
+function to be assembly code. The specified function will not have
+prologue/epilogue sequences generated by the compiler. Only basic
+@code{asm} statements can safely be included in naked functions
+(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
+basic @code{asm} and C code may appear to work, they cannot be
+depended upon to work reliably and are not supported.
+
+@cindex @code{vector} function attribute, RX
+@item vector
+This RX attribute is similar to the @code{interrupt} attribute, including its
+parameters, but does not make the function an interrupt-handler type
+function (i.e.@: it retains the normal C function calling ABI). See the
+@code{interrupt} attribute for a description of its arguments.
@end table
-@node PowerPC Function Attributes
-@subsection PowerPC Function Attributes
+@node S/390 Function Attributes
+@subsection S/390 Function Attributes
-These function attributes are supported by the PowerPC back end:
+These function attributes are supported on the S/390:
@table @code
-@cindex indirect calls, PowerPC
-@cindex @code{longcall} function attribute, PowerPC
-@cindex @code{shortcall} function attribute, PowerPC
-@item longcall
-@itemx shortcall
-The @code{longcall} attribute
-indicates that the function might be far away from the call site and
-require a different (more expensive) calling sequence. The
-@code{shortcall} attribute indicates that the function is always close
-enough for the shorter calling sequence to be used. These attributes
-override both the @option{-mlongcall} switch and
-the @code{#pragma longcall} setting.
+@cindex @code{hotpatch} function attribute, S/390
+@item hotpatch (@var{halfwords-before-function-label},@var{halfwords-after-function-label})
-@xref{RS/6000 and PowerPC Options}, for more information on whether long
-calls are necessary.
+On S/390 System z targets, you can use this function attribute to
+make GCC generate a ``hot-patching'' function prologue. If the
+@option{-mhotpatch=} command-line option is used at the same time,
+the @code{hotpatch} attribute takes precedence. The first of the
+two arguments specifies the number of halfwords to be added before
+the function label. A second argument can be used to specify the
+number of halfwords to be added after the function label. For
+both arguments the maximum allowed value is 1000000.
+
+If both arguments are zero, hotpatching is disabled.
@cindex @code{target} function attribute
@item target (@var{options})
-As discussed in @ref{Common Function Attributes}, this attribute
+As discussed in @ref{Common Function Attributes}, this attribute
allows specification of target-specific compilation options.
-On the PowerPC, the following options are allowed:
+On S/390, the following options are supported:
@table @samp
-@cindex @code{target("altivec")} function attribute, PowerPC
-@item altivec
-@itemx no-altivec
-Generate code that uses (does not use) AltiVec instructions. In
-32-bit code, you cannot enable AltiVec instructions unless
-@option{-mabi=altivec} is used on the command line.
-
-@cindex @code{target("cmpb")} function attribute, PowerPC
-@item cmpb
-@itemx no-cmpb
-Generate code that uses (does not use) the compare bytes instruction
-implemented on the POWER6 processor and other processors that support
-the PowerPC V2.05 architecture.
-
-@cindex @code{target("dlmzb")} function attribute, PowerPC
-@item dlmzb
-@itemx no-dlmzb
-Generate code that uses (does not use) the string-search @samp{dlmzb}
-instruction on the IBM 405, 440, 464 and 476 processors. This instruction is
-generated by default when targeting those processors.
-
-@cindex @code{target("fprnd")} function attribute, PowerPC
-@item fprnd
-@itemx no-fprnd
-Generate code that uses (does not use) the FP round to integer
-instructions implemented on the POWER5+ processor and other processors
-that support the PowerPC V2.03 architecture.
-
-@cindex @code{target("hard-dfp")} function attribute, PowerPC
+@item arch=
+@item tune=
+@item stack-guard=
+@item stack-size=
+@item branch-cost=
+@item warn-framesize=
+@item backchain
+@itemx no-backchain
@item hard-dfp
@itemx no-hard-dfp
-Generate code that uses (does not use) the decimal floating-point
-instructions implemented on some POWER processors.
-
-@cindex @code{target("isel")} function attribute, PowerPC
-@item isel
-@itemx no-isel
-Generate code that uses (does not use) ISEL instruction.
-
-@cindex @code{target("mfcrf")} function attribute, PowerPC
-@item mfcrf
-@itemx no-mfcrf
-Generate code that uses (does not use) the move from condition
-register field instruction implemented on the POWER4 processor and
-other processors that support the PowerPC V2.01 architecture.
+@item hard-float
+@itemx soft-float
+@item htm
+@itemx no-htm
+@item vx
+@itemx no-vx
+@item packed-stack
+@itemx no-packed-stack
+@item small-exec
+@itemx no-small-exec
+@item mvcle
+@itemx no-mvcle
+@item warn-dynamicstack
+@itemx no-warn-dynamicstack
+@end table
-@cindex @code{target("mulhw")} function attribute, PowerPC
-@item mulhw
-@itemx no-mulhw
-Generate code that uses (does not use) the half-word multiply and
-multiply-accumulate instructions on the IBM 405, 440, 464 and 476 processors.
-These instructions are generated by default when targeting those
-processors.
+The options work exactly like the S/390 specific command line
+options (without the prefix @option{-m}) except that they do not
+change any feature macros. For example,
-@cindex @code{target("multiple")} function attribute, PowerPC
-@item multiple
-@itemx no-multiple
-Generate code that uses (does not use) the load multiple word
-instructions and the store multiple word instructions.
+@smallexample
+@code{target("no-vx")}
+@end smallexample
-@cindex @code{target("update")} function attribute, PowerPC
-@item update
-@itemx no-update
-Generate code that uses (does not use) the load or store instructions
-that update the base register to the address of the calculated memory
-location.
+does not undefine the @code{__VEC__} macro.
+@end table
-@cindex @code{target("popcntb")} function attribute, PowerPC
-@item popcntb
-@itemx no-popcntb
-Generate code that uses (does not use) the popcount and double-precision
-FP reciprocal estimate instruction implemented on the POWER5
-processor and other processors that support the PowerPC V2.02
-architecture.
+@node SH Function Attributes
+@subsection SH Function Attributes
-@cindex @code{target("popcntd")} function attribute, PowerPC
-@item popcntd
-@itemx no-popcntd
-Generate code that uses (does not use) the popcount instruction
-implemented on the POWER7 processor and other processors that support
-the PowerPC V2.06 architecture.
+These function attributes are supported on the SH family of processors:
-@cindex @code{target("powerpc-gfxopt")} function attribute, PowerPC
-@item powerpc-gfxopt
-@itemx no-powerpc-gfxopt
-Generate code that uses (does not use) the optional PowerPC
-architecture instructions in the Graphics group, including
-floating-point select.
+@table @code
+@cindex @code{function_vector} function attribute, SH
+@cindex calling functions through the function vector on SH2A
+@item function_vector
+On SH2A targets, this attribute declares a function to be called using the
+TBR relative addressing mode. The argument to this attribute is the entry
+number of the same function in a vector table containing all the TBR
+relative addressable functions. For correct operation the TBR must be setup
+accordingly to point to the start of the vector table before any functions with
+this attribute are invoked. Usually a good place to do the initialization is
+the startup routine. The TBR relative vector table can have at max 256 function
+entries. The jumps to these functions are generated using a SH2A specific,
+non delayed branch instruction JSR/N @@(disp8,TBR). You must use GAS and GLD
+from GNU binutils version 2.7 or later for this attribute to work correctly.
-@cindex @code{target("powerpc-gpopt")} function attribute, PowerPC
-@item powerpc-gpopt
-@itemx no-powerpc-gpopt
-Generate code that uses (does not use) the optional PowerPC
-architecture instructions in the General Purpose group, including
-floating-point square root.
+In an application, for a function being called once, this attribute
+saves at least 8 bytes of code; and if other successive calls are being
+made to the same function, it saves 2 bytes of code per each of these
+calls.
-@cindex @code{target("recip-precision")} function attribute, PowerPC
-@item recip-precision
-@itemx no-recip-precision
-Assume (do not assume) that the reciprocal estimate instructions
-provide higher-precision estimates than is mandated by the PowerPC
-ABI.
+@cindex @code{interrupt_handler} function attribute, SH
+@item interrupt_handler
+Use this attribute to
+indicate that the specified function is an interrupt handler. The compiler
+generates function entry and exit sequences suitable for use in an
+interrupt handler when this attribute is present.
-@cindex @code{target("string")} function attribute, PowerPC
-@item string
-@itemx no-string
-Generate code that uses (does not use) the load string instructions
-and the store string word instructions to save multiple registers and
-do small block moves.
+@cindex @code{nosave_low_regs} function attribute, SH
+@item nosave_low_regs
+Use this attribute on SH targets to indicate that an @code{interrupt_handler}
+function should not save and restore registers R0..R7. This can be used on SH3*
+and SH4* targets that have a second R0..R7 register bank for non-reentrant
+interrupt handlers.
-@cindex @code{target("vsx")} function attribute, PowerPC
-@item vsx
-@itemx no-vsx
-Generate code that uses (does not use) vector/scalar (VSX)
-instructions, and also enable the use of built-in functions that allow
-more direct access to the VSX instruction set. In 32-bit code, you
-cannot enable VSX or AltiVec instructions unless
-@option{-mabi=altivec} is used on the command line.
+@cindex @code{renesas} function attribute, SH
+@item renesas
+On SH targets this attribute specifies that the function or struct follows the
+Renesas ABI.
-@cindex @code{target("friz")} function attribute, PowerPC
-@item friz
-@itemx no-friz
-Generate (do not generate) the @code{friz} instruction when the
-@option{-funsafe-math-optimizations} option is used to optimize
-rounding a floating-point value to 64-bit integer and back to floating
-point. The @code{friz} instruction does not return the same value if
-the floating-point number is too large to fit in an integer.
+@cindex @code{resbank} function attribute, SH
+@item resbank
+On the SH2A target, this attribute enables the high-speed register
+saving and restoration using a register bank for @code{interrupt_handler}
+routines. Saving to the bank is performed automatically after the CPU
+accepts an interrupt that uses a register bank.
-@cindex @code{target("avoid-indexed-addresses")} function attribute, PowerPC
-@item avoid-indexed-addresses
-@itemx no-avoid-indexed-addresses
-Generate code that tries to avoid (not avoid) the use of indexed load
-or store instructions.
+The nineteen 32-bit registers comprising general register R0 to R14,
+control register GBR, and system registers MACH, MACL, and PR and the
+vector table address offset are saved into a register bank. Register
+banks are stacked in first-in last-out (FILO) sequence. Restoration
+from the bank is executed by issuing a RESBANK instruction.
-@cindex @code{target("paired")} function attribute, PowerPC
-@item paired
-@itemx no-paired
-Generate code that uses (does not use) the generation of PAIRED simd
-instructions.
+@cindex @code{sp_switch} function attribute, SH
+@item sp_switch
+Use this attribute on the SH to indicate an @code{interrupt_handler}
+function should switch to an alternate stack. It expects a string
+argument that names a global variable holding the address of the
+alternate stack.
-@cindex @code{target("longcall")} function attribute, PowerPC
-@item longcall
-@itemx no-longcall
-Generate code that assumes (does not assume) that all calls are far
-away so that a longer more expensive calling sequence is required.
+@smallexample
+void *alt_stack;
+void f () __attribute__ ((interrupt_handler,
+ sp_switch ("alt_stack")));
+@end smallexample
-@cindex @code{target("cpu=@var{CPU}")} function attribute, PowerPC
-@item cpu=@var{CPU}
-Specify the architecture to generate code for when compiling the
-function. If you select the @code{target("cpu=power7")} attribute when
-generating 32-bit code, VSX and AltiVec instructions are not generated
-unless you use the @option{-mabi=altivec} option on the command line.
+@cindex @code{trap_exit} function attribute, SH
+@item trap_exit
+Use this attribute on the SH for an @code{interrupt_handler} to return using
+@code{trapa} instead of @code{rte}. This attribute expects an integer
+argument specifying the trap number to be used.
-@cindex @code{target("tune=@var{TUNE}")} function attribute, PowerPC
-@item tune=@var{TUNE}
-Specify the architecture to tune for when compiling the function. If
-you do not specify the @code{target("tune=@var{TUNE}")} attribute and
-you do specify the @code{target("cpu=@var{CPU}")} attribute,
-compilation tunes for the @var{CPU} architecture, and not the
-default tuning specified on the command line.
+@cindex @code{trapa_handler} function attribute, SH
+@item trapa_handler
+On SH targets this function attribute is similar to @code{interrupt_handler}
+but it does not save and restore all registers.
@end table
-On the PowerPC, 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.
-@end table
+@node Symbian OS Function Attributes
+@subsection Symbian OS Function Attributes
-@node RISC-V Function Attributes
-@subsection RISC-V Function Attributes
+@xref{Microsoft Windows Function Attributes}, for discussion of the
+@code{dllexport} and @code{dllimport} attributes.
-These function attributes are supported by the RISC-V back end:
+@node V850 Function Attributes
+@subsection V850 Function Attributes
+
+The V850 back end supports these function attributes:
@table @code
-@cindex @code{naked} function attribute, RISC-V
-@item naked
-This attribute allows the compiler to construct the
-requisite function declaration, while allowing the body of the
-function to be assembly code. The specified function will not have
-prologue/epilogue sequences generated by the compiler. Only basic
-@code{asm} statements can safely be included in naked functions
-(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
-basic @code{asm} and C code may appear to work, they cannot be
-depended upon to work reliably and are not supported.
-
-@cindex @code{interrupt} function attribute, RISC-V
+@cindex @code{interrupt} function attribute, V850
+@cindex @code{interrupt_handler} function attribute, V850
@item interrupt
-Use this attribute to indicate that the specified function is an interrupt
-handler. The compiler generates function entry and exit sequences suitable
-for use in an interrupt handler when this attribute is present.
-
-You can specify the kind of interrupt to be handled by adding an optional
-parameter to the interrupt attribute like this:
-
-@smallexample
-void f (void) __attribute__ ((interrupt ("user")));
-@end smallexample
-
-Permissible values for this parameter are @code{user}, @code{supervisor},
-and @code{machine}. If there is no parameter, then it defaults to
-@code{machine}.
+@itemx interrupt_handler
+Use these attributes to indicate
+that the specified function is an interrupt handler. The compiler generates
+function entry and exit sequences suitable for use in an interrupt handler
+when either attribute is present.
+@end table
-@cindex @code{riscv_vector_cc} function attribute, RISC-V
-@item riscv_vector_cc
-Use this attribute to force the function to use the vector calling
-convention variant.
+@node Visium Function Attributes
+@subsection Visium Function Attributes
-@smallexample
-void foo() __attribute__((riscv_vector_cc));
-[[riscv::vector_cc]] void foo(); // For C++11 and C23
-@end smallexample
+These function attributes are supported by the Visium back end:
+@table @code
+@cindex @code{interrupt} function attribute, Visium
+@item interrupt
+Use this attribute to indicate
+that the specified function is an interrupt handler. The compiler generates
+function entry and exit sequences suitable for use in an interrupt handler
+when this attribute is present.
@end table
-The following target-specific function attributes are available for the
-RISC-V target. For the most part, these options mirror the behavior of
-similar command-line options (@pxref{RISC-V Options}), but on a
-per-function basis.
-
-@table @code
-@cindex @code{arch=} function attribute, RISC-V
-@item arch=
-Specifies the architecture version and architectural extensions to use
-for this function. The behavior and permissible arguments are the same as
-for the @option{-march=} command-line option, in addtion, it also support
-extension enablement list, a list of extension name and prefixed with @code{+},
-like @code{arch=+zba} means enable @code{zba} extension.
-Multiple extension can be enabled by separating them with a comma. For example:
-@code{arch=+zba,+zbb}.
+@node x86 Function Attributes
+@subsection x86 Function Attributes
-@cindex @code{tune=} function attribute, RISC-V
-@item tune=
-Specifies the core for which to tune the performance of this function.
-The behavior and permissible arguments are the same as for the @option{-mtune=}
-command-line option.
+These function attributes are supported by the x86 back end:
-@cindex @code{cpu=} function attribute, RISC-V
-@item cpu=
-Specifies the core for which to tune the performance of this function and also
-whose architectural features to use. The behavior and valid arguments are the
-same as for the @option{-mcpu=} command-line option.
+@table @code
+@cindex @code{cdecl} function attribute, x86-32
+@cindex functions that pop the argument stack on x86-32
+@opindex mrtd
+@item cdecl
+On the x86-32 targets, the @code{cdecl} attribute causes the compiler to
+assume that the calling function pops off the stack space used to
+pass arguments. This is
+useful to override the effects of the @option{-mrtd} switch.
-@end table
+@cindex @code{fastcall} function attribute, x86-32
+@cindex functions that pop the argument stack on x86-32
+@item fastcall
+On x86-32 targets, the @code{fastcall} attribute causes the compiler to
+pass the first argument (if of integral type) in the register ECX and
+the second argument (if of integral type) in the register EDX@. Subsequent
+and other typed arguments are passed on the stack. The called function
+pops the arguments off the stack. If the number of arguments is variable all
+arguments are pushed on the stack.
-The above target attributes can be specified as follows:
+@cindex @code{thiscall} function attribute, x86-32
+@cindex functions that pop the argument stack on x86-32
+@item thiscall
+On x86-32 targets, the @code{thiscall} attribute causes the compiler to
+pass the first argument (if of integral type) in the register ECX.
+Subsequent and other typed arguments are passed on the stack. The called
+function pops the arguments off the stack.
+If the number of arguments is variable all arguments are pushed on the
+stack.
+The @code{thiscall} attribute is intended for C++ non-static member functions.
+As a GCC extension, this calling convention can be used for C functions
+and for static member methods.
-@smallexample
-__attribute__((target("@var{attr-string}")))
-int
-f (int a)
-@{
- return a + 5;
-@}
-@end smallexample
+@cindex @code{ms_abi} function attribute, x86
+@cindex @code{sysv_abi} function attribute, x86
+@item ms_abi
+@itemx sysv_abi
-where @code{@var{attr-string}} is one of the attribute strings specified above.
+On 32-bit and 64-bit x86 targets, you can use an ABI attribute
+to indicate which calling convention should be used for a function. The
+@code{ms_abi} attribute tells the compiler to use the Microsoft ABI,
+while the @code{sysv_abi} attribute tells the compiler to use the System V
+ELF ABI, which is used on GNU/Linux and other systems. The default is to use
+the Microsoft ABI when targeting Windows. On all other systems, the default
+is the System V ELF ABI.
-Multiple target function attributes can be specified by separating them with
-a semicolon. For example:
-@smallexample
-__attribute__((target("arch=+zba,+zbb;tune=rocket")))
-int
-foo (int a)
-@{
- return a + 5;
-@}
-@end smallexample
+Note, the @code{ms_abi} attribute for Microsoft Windows 64-bit targets currently
+requires the @option{-maccumulate-outgoing-args} option.
-is valid and compiles function @code{foo} with @code{zba}
-and @code{zbb} extensions and tunes it for @code{rocket}.
+@cindex @code{callee_pop_aggregate_return} function attribute, x86
+@item callee_pop_aggregate_return (@var{number})
-@node RL78 Function Attributes
-@subsection RL78 Function Attributes
+On x86-32 targets, you can use this attribute to control how
+aggregates are returned in memory. If the caller is responsible for
+popping the hidden pointer together with the rest of the arguments, specify
+@var{number} equal to zero. If callee is responsible for popping the
+hidden pointer, specify @var{number} equal to one.
-These function attributes are supported by the RL78 back end:
+The default x86-32 ABI assumes that the callee pops the
+stack for hidden pointer. However, on x86-32 Microsoft Windows targets,
+the compiler assumes that the
+caller pops the stack for hidden pointer.
-@table @code
-@cindex @code{interrupt} function attribute, RL78
-@cindex @code{brk_interrupt} function attribute, RL78
-@item interrupt
-@itemx brk_interrupt
-These attributes indicate
-that the specified function is an interrupt handler. The compiler generates
-function entry and exit sequences suitable for use in an interrupt handler
-when this attribute is present.
+@cindex @code{ms_hook_prologue} function attribute, x86
+@item ms_hook_prologue
-Use @code{brk_interrupt} instead of @code{interrupt} for
-handlers intended to be used with the @code{BRK} opcode (i.e.@: those
-that must end with @code{RETB} instead of @code{RETI}).
+On 32-bit and 64-bit x86 targets, you can use
+this function attribute to make GCC generate the ``hot-patching'' function
+prologue used in Win32 API functions in Microsoft Windows XP Service Pack 2
+and newer.
-@cindex @code{naked} function attribute, RL78
+@cindex @code{naked} function attribute, x86
@item naked
This attribute allows the compiler to construct the
requisite function declaration, while allowing the body of the
(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
basic @code{asm} and C code may appear to work, they cannot be
depended upon to work reliably and are not supported.
-@end table
-
-@node RX Function Attributes
-@subsection RX Function Attributes
-These function attributes are supported by the RX back end:
+@cindex @code{regparm} function attribute, x86
+@cindex functions that are passed arguments in registers on x86-32
+@item regparm (@var{number})
+On x86-32 targets, the @code{regparm} attribute causes the compiler to
+pass arguments number one to @var{number} if they are of integral type
+in registers EAX, EDX, and ECX instead of on the stack. Functions that
+take a variable number of arguments continue to be passed all of their
+arguments on the stack.
-@table @code
-@cindex @code{fast_interrupt} function attribute, RX
-@item fast_interrupt
-Use this attribute on the RX port to indicate that the specified
-function is a fast interrupt handler. This is just like the
-@code{interrupt} attribute, except that @code{freit} is used to return
-instead of @code{reit}.
+Beware that on some ELF systems this attribute is unsuitable for
+global functions in shared libraries with lazy binding (which is the
+default). Lazy binding sends the first call via resolving code in
+the loader, which might assume EAX, EDX and ECX can be clobbered, as
+per the standard calling conventions. Solaris 8 is affected by this.
+Systems with the GNU C Library version 2.1 or higher
+and FreeBSD are believed to be
+safe since the loaders there save EAX, EDX and ECX. (Lazy binding can be
+disabled with the linker or the loader if desired, to avoid the
+problem.)
-@cindex @code{interrupt} function attribute, RX
-@item interrupt
-Use this attribute to indicate
-that the specified function is an interrupt handler. The compiler generates
-function entry and exit sequences suitable for use in an interrupt handler
-when this attribute is present.
+@cindex @code{sseregparm} function attribute, x86
+@item sseregparm
+On x86-32 targets with SSE support, the @code{sseregparm} attribute
+causes the compiler to pass up to 3 floating-point arguments in
+SSE registers instead of on the stack. Functions that take a
+variable number of arguments continue to pass all of their
+floating-point arguments on the stack.
-On RX and RL78 targets, you may specify one or more vector numbers as arguments
-to the attribute, as well as naming an alternate table name.
-Parameters are handled sequentially, so one handler can be assigned to
-multiple entries in multiple tables. One may also pass the magic
-string @code{"$default"} which causes the function to be used for any
-unfilled slots in the current table.
+@cindex @code{force_align_arg_pointer} function attribute, x86
+@item force_align_arg_pointer
+On x86 targets, the @code{force_align_arg_pointer} attribute may be
+applied to individual function definitions, generating an alternate
+prologue and epilogue that realigns the run-time stack if necessary.
+This supports mixing legacy codes that run with a 4-byte aligned stack
+with modern codes that keep a 16-byte stack for SSE compatibility.
-This example shows a simple assignment of a function to one vector in
-the default table (note that preprocessor macros may be used for
-chip-specific symbolic vector names):
-@smallexample
-void __attribute__ ((interrupt (5))) txd1_handler ();
-@end smallexample
+@cindex @code{stdcall} function attribute, x86-32
+@cindex functions that pop the argument stack on x86-32
+@item stdcall
+On x86-32 targets, the @code{stdcall} attribute causes the compiler to
+assume that the called function pops off the stack space used to
+pass arguments, unless it takes a variable number of arguments.
-This example assigns a function to two slots in the default table
-(using preprocessor macros defined elsewhere) and makes it the default
-for the @code{dct} table:
-@smallexample
-void __attribute__ ((interrupt (RXD1_VECT,RXD2_VECT,"dct","$default")))
- txd1_handler ();
-@end smallexample
+@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.
-@cindex @code{naked} function attribute, RX
-@item naked
-This attribute allows the compiler to construct the
-requisite function declaration, while allowing the body of the
-function to be assembly code. The specified function will not have
-prologue/epilogue sequences generated by the compiler. Only basic
-@code{asm} statements can safely be included in naked functions
-(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
-basic @code{asm} and C code may appear to work, they cannot be
-depended upon to work reliably and are not supported.
+@cindex @code{no_caller_saved_registers} function attribute, x86
+@item no_caller_saved_registers
+Use this attribute to indicate that the specified function has no
+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.
-@cindex @code{vector} function attribute, RX
-@item vector
-This RX attribute is similar to the @code{interrupt} attribute, including its
-parameters, but does not make the function an interrupt-handler type
-function (i.e.@: it retains the normal C function calling ABI). See the
-@code{interrupt} attribute for a description of its arguments.
-@end table
+@cindex @code{interrupt} function attribute, x86
+@item interrupt
+Use this attribute to indicate that the specified function is an
+interrupt handler or an exception handler (depending on parameters passed
+to the function, explained further). The compiler generates function
+entry and exit sequences suitable for use in an interrupt handler when
+this attribute is present. The @code{IRET} instruction, instead of the
+@code{RET} instruction, is used to return from interrupt handlers. All
+registers, except for the EFLAGS register which is restored by the
+@code{IRET} instruction, are preserved by the compiler. Since GCC
+doesn't preserve SSE, MMX nor x87 states, the GCC option
+@option{-mgeneral-regs-only} should be used to compile interrupt and
+exception handlers.
-@node S/390 Function Attributes
-@subsection S/390 Function Attributes
+Any interruptible-without-stack-switch code must be compiled with
+@option{-mno-red-zone} since interrupt handlers can and will, because
+of the hardware design, touch the red zone.
-These function attributes are supported on the S/390:
+An interrupt handler must be declared with a mandatory pointer
+argument:
-@table @code
-@cindex @code{hotpatch} function attribute, S/390
-@item hotpatch (@var{halfwords-before-function-label},@var{halfwords-after-function-label})
+@smallexample
+struct interrupt_frame;
-On S/390 System z targets, you can use this function attribute to
-make GCC generate a ``hot-patching'' function prologue. If the
-@option{-mhotpatch=} command-line option is used at the same time,
-the @code{hotpatch} attribute takes precedence. The first of the
-two arguments specifies the number of halfwords to be added before
-the function label. A second argument can be used to specify the
-number of halfwords to be added after the function label. For
-both arguments the maximum allowed value is 1000000.
+__attribute__ ((interrupt))
+void
+f (struct interrupt_frame *frame)
+@{
+@}
+@end smallexample
-If both arguments are zero, hotpatching is disabled.
+@noindent
+and you must define @code{struct interrupt_frame} as described in the
+processor's manual.
+
+Exception handlers differ from interrupt handlers because the system
+pushes an error code on the stack. An exception handler declaration is
+similar to that for an interrupt handler, but with a different mandatory
+function signature. The compiler arranges to pop the error code off the
+stack before the @code{IRET} instruction.
+
+@smallexample
+#ifdef __x86_64__
+typedef unsigned long long int uword_t;
+#else
+typedef unsigned int uword_t;
+#endif
+
+struct interrupt_frame;
+
+__attribute__ ((interrupt))
+void
+f (struct interrupt_frame *frame, uword_t error_code)
+@{
+ ...
+@}
+@end smallexample
+
+Exception handlers should only be used for exceptions that push an error
+code; you should use an interrupt handler in other cases. The system
+will crash if the wrong kind of handler is used.
@cindex @code{target} function attribute
@item target (@var{options})
-As discussed in @ref{Common Function Attributes}, this attribute
+As discussed in @ref{Common Function Attributes}, this attribute
allows specification of target-specific compilation options.
-On S/390, the following options are supported:
-
+On the x86, the following options are allowed:
@table @samp
-@item arch=
-@item tune=
-@item stack-guard=
-@item stack-size=
-@item branch-cost=
-@item warn-framesize=
-@item backchain
-@itemx no-backchain
-@item hard-dfp
-@itemx no-hard-dfp
-@item hard-float
-@itemx soft-float
-@item htm
-@itemx no-htm
-@item vx
-@itemx no-vx
-@item packed-stack
-@itemx no-packed-stack
-@item small-exec
-@itemx no-small-exec
-@item mvcle
-@itemx no-mvcle
-@item warn-dynamicstack
-@itemx no-warn-dynamicstack
-@end table
+@cindex @code{target("3dnow")} function attribute, x86
+@item 3dnow
+@itemx no-3dnow
+Enable/disable the generation of the 3DNow!@: instructions.
-The options work exactly like the S/390 specific command line
-options (without the prefix @option{-m}) except that they do not
-change any feature macros. For example,
+@cindex @code{target("3dnowa")} function attribute, x86
+@item 3dnowa
+@itemx no-3dnowa
+Enable/disable the generation of the enhanced 3DNow!@: instructions.
-@smallexample
-@code{target("no-vx")}
-@end smallexample
+@cindex @code{target("abm")} function attribute, x86
+@item abm
+@itemx no-abm
+Enable/disable the generation of the advanced bit instructions.
-does not undefine the @code{__VEC__} macro.
-@end table
+@cindex @code{target("adx")} function attribute, x86
+@item adx
+@itemx no-adx
+Enable/disable the generation of the ADX instructions.
-@node SH Function Attributes
-@subsection SH Function Attributes
+@cindex @code{target("aes")} function attribute, x86
+@item aes
+@itemx no-aes
+Enable/disable the generation of the AES instructions.
-These function attributes are supported on the SH family of processors:
+@cindex @code{target("avx")} function attribute, x86
+@item avx
+@itemx no-avx
+Enable/disable the generation of the AVX instructions.
-@table @code
-@cindex @code{function_vector} function attribute, SH
-@cindex calling functions through the function vector on SH2A
-@item function_vector
-On SH2A targets, this attribute declares a function to be called using the
-TBR relative addressing mode. The argument to this attribute is the entry
-number of the same function in a vector table containing all the TBR
-relative addressable functions. For correct operation the TBR must be setup
-accordingly to point to the start of the vector table before any functions with
-this attribute are invoked. Usually a good place to do the initialization is
-the startup routine. The TBR relative vector table can have at max 256 function
-entries. The jumps to these functions are generated using a SH2A specific,
-non delayed branch instruction JSR/N @@(disp8,TBR). You must use GAS and GLD
-from GNU binutils version 2.7 or later for this attribute to work correctly.
+@cindex @code{target("avx2")} function attribute, x86
+@item avx2
+@itemx no-avx2
+Enable/disable the generation of the AVX2 instructions.
-In an application, for a function being called once, this attribute
-saves at least 8 bytes of code; and if other successive calls are being
-made to the same function, it saves 2 bytes of code per each of these
-calls.
+@cindex @code{target("avx512bitalg")} function attribute, x86
+@item avx512bitalg
+@itemx no-avx512bitalg
+Enable/disable the generation of the AVX512BITALG instructions.
-@cindex @code{interrupt_handler} function attribute, SH
-@item interrupt_handler
-Use this attribute to
-indicate that the specified function is an interrupt handler. The compiler
-generates function entry and exit sequences suitable for use in an
-interrupt handler when this attribute is present.
+@cindex @code{target("avx512bw")} function attribute, x86
+@item avx512bw
+@itemx no-avx512bw
+Enable/disable the generation of the AVX512BW instructions.
-@cindex @code{nosave_low_regs} function attribute, SH
-@item nosave_low_regs
-Use this attribute on SH targets to indicate that an @code{interrupt_handler}
-function should not save and restore registers R0..R7. This can be used on SH3*
-and SH4* targets that have a second R0..R7 register bank for non-reentrant
-interrupt handlers.
+@cindex @code{target("avx512cd")} function attribute, x86
+@item avx512cd
+@itemx no-avx512cd
+Enable/disable the generation of the AVX512CD instructions.
-@cindex @code{renesas} function attribute, SH
-@item renesas
-On SH targets this attribute specifies that the function or struct follows the
-Renesas ABI.
+@cindex @code{target("avx512dq")} function attribute, x86
+@item avx512dq
+@itemx no-avx512dq
+Enable/disable the generation of the AVX512DQ instructions.
-@cindex @code{resbank} function attribute, SH
-@item resbank
-On the SH2A target, this attribute enables the high-speed register
-saving and restoration using a register bank for @code{interrupt_handler}
-routines. Saving to the bank is performed automatically after the CPU
-accepts an interrupt that uses a register bank.
+@cindex @code{target("avx512er")} function attribute, x86
+@item avx512er
+@itemx no-avx512er
+Enable/disable the generation of the AVX512ER instructions.
-The nineteen 32-bit registers comprising general register R0 to R14,
-control register GBR, and system registers MACH, MACL, and PR and the
-vector table address offset are saved into a register bank. Register
-banks are stacked in first-in last-out (FILO) sequence. Restoration
-from the bank is executed by issuing a RESBANK instruction.
+@cindex @code{target("avx512f")} function attribute, x86
+@item avx512f
+@itemx no-avx512f
+Enable/disable the generation of the AVX512F instructions.
-@cindex @code{sp_switch} function attribute, SH
-@item sp_switch
-Use this attribute on the SH to indicate an @code{interrupt_handler}
-function should switch to an alternate stack. It expects a string
-argument that names a global variable holding the address of the
-alternate stack.
+@cindex @code{target("avx512ifma")} function attribute, x86
+@item avx512ifma
+@itemx no-avx512ifma
+Enable/disable the generation of the AVX512IFMA instructions.
-@smallexample
-void *alt_stack;
-void f () __attribute__ ((interrupt_handler,
- sp_switch ("alt_stack")));
-@end smallexample
+@cindex @code{target("avx512vbmi")} function attribute, x86
+@item avx512vbmi
+@itemx no-avx512vbmi
+Enable/disable the generation of the AVX512VBMI instructions.
-@cindex @code{trap_exit} function attribute, SH
-@item trap_exit
-Use this attribute on the SH for an @code{interrupt_handler} to return using
-@code{trapa} instead of @code{rte}. This attribute expects an integer
-argument specifying the trap number to be used.
+@cindex @code{target("avx512vbmi2")} function attribute, x86
+@item avx512vbmi2
+@itemx no-avx512vbmi2
+Enable/disable the generation of the AVX512VBMI2 instructions.
-@cindex @code{trapa_handler} function attribute, SH
-@item trapa_handler
-On SH targets this function attribute is similar to @code{interrupt_handler}
-but it does not save and restore all registers.
-@end table
+@cindex @code{target("avx512vl")} function attribute, x86
+@item avx512vl
+@itemx no-avx512vl
+Enable/disable the generation of the AVX512VL instructions.
-@node Symbian OS Function Attributes
-@subsection Symbian OS Function Attributes
+@cindex @code{target("avx512vnni")} function attribute, x86
+@item avx512vnni
+@itemx no-avx512vnni
+Enable/disable the generation of the AVX512VNNI instructions.
-@xref{Microsoft Windows Function Attributes}, for discussion of the
-@code{dllexport} and @code{dllimport} attributes.
+@cindex @code{target("avx512vpopcntdq")} function attribute, x86
+@item avx512vpopcntdq
+@itemx no-avx512vpopcntdq
+Enable/disable the generation of the AVX512VPOPCNTDQ instructions.
-@node V850 Function Attributes
-@subsection V850 Function Attributes
+@cindex @code{target("bmi")} function attribute, x86
+@item bmi
+@itemx no-bmi
+Enable/disable the generation of the BMI instructions.
-The V850 back end supports these function attributes:
+@cindex @code{target("bmi2")} function attribute, x86
+@item bmi2
+@itemx no-bmi2
+Enable/disable the generation of the BMI2 instructions.
-@table @code
-@cindex @code{interrupt} function attribute, V850
-@cindex @code{interrupt_handler} function attribute, V850
-@item interrupt
-@itemx interrupt_handler
-Use these attributes to indicate
-that the specified function is an interrupt handler. The compiler generates
-function entry and exit sequences suitable for use in an interrupt handler
-when either attribute is present.
-@end table
+@cindex @code{target("cldemote")} function attribute, x86
+@item cldemote
+@itemx no-cldemote
+Enable/disable the generation of the CLDEMOTE instructions.
-@node Visium Function Attributes
-@subsection Visium Function Attributes
+@cindex @code{target("clflushopt")} function attribute, x86
+@item clflushopt
+@itemx no-clflushopt
+Enable/disable the generation of the CLFLUSHOPT instructions.
-These function attributes are supported by the Visium back end:
+@cindex @code{target("clwb")} function attribute, x86
+@item clwb
+@itemx no-clwb
+Enable/disable the generation of the CLWB instructions.
-@table @code
-@cindex @code{interrupt} function attribute, Visium
-@item interrupt
-Use this attribute to indicate
-that the specified function is an interrupt handler. The compiler generates
-function entry and exit sequences suitable for use in an interrupt handler
-when this attribute is present.
-@end table
+@cindex @code{target("clzero")} function attribute, x86
+@item clzero
+@itemx no-clzero
+Enable/disable the generation of the CLZERO instructions.
-@node x86 Function Attributes
-@subsection x86 Function Attributes
+@cindex @code{target("crc32")} function attribute, x86
+@item crc32
+@itemx no-crc32
+Enable/disable the generation of the CRC32 instructions.
-These function attributes are supported by the x86 back end:
+@cindex @code{target("cx16")} function attribute, x86
+@item cx16
+@itemx no-cx16
+Enable/disable the generation of the CMPXCHG16B instructions.
-@table @code
-@cindex @code{cdecl} function attribute, x86-32
-@cindex functions that pop the argument stack on x86-32
-@opindex mrtd
-@item cdecl
-On the x86-32 targets, the @code{cdecl} attribute causes the compiler to
-assume that the calling function pops off the stack space used to
-pass arguments. This is
-useful to override the effects of the @option{-mrtd} switch.
+@cindex @code{target("default")} function attribute, x86
+@item default
+@xref{Function Multiversioning}, where it is used to specify the
+default function version.
-@cindex @code{fastcall} function attribute, x86-32
-@cindex functions that pop the argument stack on x86-32
-@item fastcall
-On x86-32 targets, the @code{fastcall} attribute causes the compiler to
-pass the first argument (if of integral type) in the register ECX and
-the second argument (if of integral type) in the register EDX@. Subsequent
-and other typed arguments are passed on the stack. The called function
-pops the arguments off the stack. If the number of arguments is variable all
-arguments are pushed on the stack.
+@cindex @code{target("f16c")} function attribute, x86
+@item f16c
+@itemx no-f16c
+Enable/disable the generation of the F16C instructions.
-@cindex @code{thiscall} function attribute, x86-32
-@cindex functions that pop the argument stack on x86-32
-@item thiscall
-On x86-32 targets, the @code{thiscall} attribute causes the compiler to
-pass the first argument (if of integral type) in the register ECX.
-Subsequent and other typed arguments are passed on the stack. The called
-function pops the arguments off the stack.
-If the number of arguments is variable all arguments are pushed on the
-stack.
-The @code{thiscall} attribute is intended for C++ non-static member functions.
-As a GCC extension, this calling convention can be used for C functions
-and for static member methods.
+@cindex @code{target("fma")} function attribute, x86
+@item fma
+@itemx no-fma
+Enable/disable the generation of the FMA instructions.
-@cindex @code{ms_abi} function attribute, x86
-@cindex @code{sysv_abi} function attribute, x86
-@item ms_abi
-@itemx sysv_abi
+@cindex @code{target("fma4")} function attribute, x86
+@item fma4
+@itemx no-fma4
+Enable/disable the generation of the FMA4 instructions.
-On 32-bit and 64-bit x86 targets, you can use an ABI attribute
-to indicate which calling convention should be used for a function. The
-@code{ms_abi} attribute tells the compiler to use the Microsoft ABI,
-while the @code{sysv_abi} attribute tells the compiler to use the System V
-ELF ABI, which is used on GNU/Linux and other systems. The default is to use
-the Microsoft ABI when targeting Windows. On all other systems, the default
-is the System V ELF ABI.
+@cindex @code{target("fsgsbase")} function attribute, x86
+@item fsgsbase
+@itemx no-fsgsbase
+Enable/disable the generation of the FSGSBASE instructions.
-Note, the @code{ms_abi} attribute for Microsoft Windows 64-bit targets currently
-requires the @option{-maccumulate-outgoing-args} option.
+@cindex @code{target("fxsr")} function attribute, x86
+@item fxsr
+@itemx no-fxsr
+Enable/disable the generation of the FXSR instructions.
-@cindex @code{callee_pop_aggregate_return} function attribute, x86
-@item callee_pop_aggregate_return (@var{number})
+@cindex @code{target("gfni")} function attribute, x86
+@item gfni
+@itemx no-gfni
+Enable/disable the generation of the GFNI instructions.
-On x86-32 targets, you can use this attribute to control how
-aggregates are returned in memory. If the caller is responsible for
-popping the hidden pointer together with the rest of the arguments, specify
-@var{number} equal to zero. If callee is responsible for popping the
-hidden pointer, specify @var{number} equal to one.
+@cindex @code{target("hle")} function attribute, x86
+@item hle
+@itemx no-hle
+Enable/disable the generation of the HLE instruction prefixes.
-The default x86-32 ABI assumes that the callee pops the
-stack for hidden pointer. However, on x86-32 Microsoft Windows targets,
-the compiler assumes that the
-caller pops the stack for hidden pointer.
+@cindex @code{target("lwp")} function attribute, x86
+@item lwp
+@itemx no-lwp
+Enable/disable the generation of the LWP instructions.
-@cindex @code{ms_hook_prologue} function attribute, x86
-@item ms_hook_prologue
+@cindex @code{target("lzcnt")} function attribute, x86
+@item lzcnt
+@itemx no-lzcnt
+Enable/disable the generation of the LZCNT instructions.
-On 32-bit and 64-bit x86 targets, you can use
-this function attribute to make GCC generate the ``hot-patching'' function
-prologue used in Win32 API functions in Microsoft Windows XP Service Pack 2
-and newer.
+@cindex @code{target("mmx")} function attribute, x86
+@item mmx
+@itemx no-mmx
+Enable/disable the generation of the MMX instructions.
-@cindex @code{naked} function attribute, x86
-@item naked
-This attribute allows the compiler to construct the
-requisite function declaration, while allowing the body of the
-function to be assembly code. The specified function will not have
-prologue/epilogue sequences generated by the compiler. Only basic
-@code{asm} statements can safely be included in naked functions
-(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
-basic @code{asm} and C code may appear to work, they cannot be
-depended upon to work reliably and are not supported.
+@cindex @code{target("movbe")} function attribute, x86
+@item movbe
+@itemx no-movbe
+Enable/disable the generation of the MOVBE instructions.
-@cindex @code{regparm} function attribute, x86
-@cindex functions that are passed arguments in registers on x86-32
-@item regparm (@var{number})
-On x86-32 targets, the @code{regparm} attribute causes the compiler to
-pass arguments number one to @var{number} if they are of integral type
-in registers EAX, EDX, and ECX instead of on the stack. Functions that
-take a variable number of arguments continue to be passed all of their
-arguments on the stack.
+@cindex @code{target("movdir64b")} function attribute, x86
+@item movdir64b
+@itemx no-movdir64b
+Enable/disable the generation of the MOVDIR64B instructions.
-Beware that on some ELF systems this attribute is unsuitable for
-global functions in shared libraries with lazy binding (which is the
-default). Lazy binding sends the first call via resolving code in
-the loader, which might assume EAX, EDX and ECX can be clobbered, as
-per the standard calling conventions. Solaris 8 is affected by this.
-Systems with the GNU C Library version 2.1 or higher
-and FreeBSD are believed to be
-safe since the loaders there save EAX, EDX and ECX. (Lazy binding can be
-disabled with the linker or the loader if desired, to avoid the
-problem.)
+@cindex @code{target("movdiri")} function attribute, x86
+@item movdiri
+@itemx no-movdiri
+Enable/disable the generation of the MOVDIRI instructions.
-@cindex @code{sseregparm} function attribute, x86
-@item sseregparm
-On x86-32 targets with SSE support, the @code{sseregparm} attribute
-causes the compiler to pass up to 3 floating-point arguments in
-SSE registers instead of on the stack. Functions that take a
-variable number of arguments continue to pass all of their
-floating-point arguments on the stack.
+@cindex @code{target("mwait")} function attribute, x86
+@item mwait
+@itemx no-mwait
+Enable/disable the generation of the MWAIT and MONITOR instructions.
-@cindex @code{force_align_arg_pointer} function attribute, x86
-@item force_align_arg_pointer
-On x86 targets, the @code{force_align_arg_pointer} attribute may be
-applied to individual function definitions, generating an alternate
-prologue and epilogue that realigns the run-time stack if necessary.
-This supports mixing legacy codes that run with a 4-byte aligned stack
-with modern codes that keep a 16-byte stack for SSE compatibility.
+@cindex @code{target("mwaitx")} function attribute, x86
+@item mwaitx
+@itemx no-mwaitx
+Enable/disable the generation of the MWAITX instructions.
-@cindex @code{stdcall} function attribute, x86-32
-@cindex functions that pop the argument stack on x86-32
-@item stdcall
-On x86-32 targets, the @code{stdcall} attribute causes the compiler to
-assume that the called function pops off the stack space used to
-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.
+@cindex @code{target("pclmul")} function attribute, x86
+@item pclmul
+@itemx no-pclmul
+Enable/disable the generation of the PCLMUL instructions.
-@cindex @code{no_caller_saved_registers} function attribute, x86
-@item no_caller_saved_registers
-Use this attribute to indicate that the specified function has no
-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.
+@cindex @code{target("pconfig")} function attribute, x86
+@item pconfig
+@itemx no-pconfig
+Enable/disable the generation of the PCONFIG instructions.
-@cindex @code{interrupt} function attribute, x86
-@item interrupt
-Use this attribute to indicate that the specified function is an
-interrupt handler or an exception handler (depending on parameters passed
-to the function, explained further). The compiler generates function
-entry and exit sequences suitable for use in an interrupt handler when
-this attribute is present. The @code{IRET} instruction, instead of the
-@code{RET} instruction, is used to return from interrupt handlers. All
-registers, except for the EFLAGS register which is restored by the
-@code{IRET} instruction, are preserved by the compiler. Since GCC
-doesn't preserve SSE, MMX nor x87 states, the GCC option
-@option{-mgeneral-regs-only} should be used to compile interrupt and
-exception handlers.
+@cindex @code{target("pku")} function attribute, x86
+@item pku
+@itemx no-pku
+Enable/disable the generation of the PKU instructions.
-Any interruptible-without-stack-switch code must be compiled with
-@option{-mno-red-zone} since interrupt handlers can and will, because
-of the hardware design, touch the red zone.
+@cindex @code{target("popcnt")} function attribute, x86
+@item popcnt
+@itemx no-popcnt
+Enable/disable the generation of the POPCNT instruction.
-An interrupt handler must be declared with a mandatory pointer
-argument:
+@cindex @code{target("prfchw")} function attribute, x86
+@item prfchw
+@itemx no-prfchw
+Enable/disable the generation of the PREFETCHW instruction.
-@smallexample
-struct interrupt_frame;
+@cindex @code{target("ptwrite")} function attribute, x86
+@item ptwrite
+@itemx no-ptwrite
+Enable/disable the generation of the PTWRITE instructions.
-__attribute__ ((interrupt))
-void
-f (struct interrupt_frame *frame)
-@{
-@}
-@end smallexample
+@cindex @code{target("rdpid")} function attribute, x86
+@item rdpid
+@itemx no-rdpid
+Enable/disable the generation of the RDPID instructions.
-@noindent
-and you must define @code{struct interrupt_frame} as described in the
-processor's manual.
+@cindex @code{target("rdrnd")} function attribute, x86
+@item rdrnd
+@itemx no-rdrnd
+Enable/disable the generation of the RDRND instructions.
-Exception handlers differ from interrupt handlers because the system
-pushes an error code on the stack. An exception handler declaration is
-similar to that for an interrupt handler, but with a different mandatory
-function signature. The compiler arranges to pop the error code off the
-stack before the @code{IRET} instruction.
+@cindex @code{target("rdseed")} function attribute, x86
+@item rdseed
+@itemx no-rdseed
+Enable/disable the generation of the RDSEED instructions.
-@smallexample
-#ifdef __x86_64__
-typedef unsigned long long int uword_t;
-#else
-typedef unsigned int uword_t;
-#endif
+@cindex @code{target("rtm")} function attribute, x86
+@item rtm
+@itemx no-rtm
+Enable/disable the generation of the RTM instructions.
-struct interrupt_frame;
+@cindex @code{target("sahf")} function attribute, x86
+@item sahf
+@itemx no-sahf
+Enable/disable the generation of the SAHF instructions.
-__attribute__ ((interrupt))
-void
-f (struct interrupt_frame *frame, uword_t error_code)
-@{
- ...
-@}
-@end smallexample
+@cindex @code{target("sgx")} function attribute, x86
+@item sgx
+@itemx no-sgx
+Enable/disable the generation of the SGX instructions.
-Exception handlers should only be used for exceptions that push an error
-code; you should use an interrupt handler in other cases. The system
-will crash if the wrong kind of handler is used.
+@cindex @code{target("sha")} function attribute, x86
+@item sha
+@itemx no-sha
+Enable/disable the generation of the SHA instructions.
-@cindex @code{target} function attribute
-@item target (@var{options})
-As discussed in @ref{Common Function Attributes}, this attribute
-allows specification of target-specific compilation options.
+@cindex @code{target("shstk")} function attribute, x86
+@item shstk
+@itemx no-shstk
+Enable/disable the shadow stack built-in functions from CET.
-On the x86, the following options are allowed:
-@table @samp
-@cindex @code{target("3dnow")} function attribute, x86
-@item 3dnow
-@itemx no-3dnow
-Enable/disable the generation of the 3DNow!@: instructions.
+@cindex @code{target("sse")} function attribute, x86
+@item sse
+@itemx no-sse
+Enable/disable the generation of the SSE instructions.
-@cindex @code{target("3dnowa")} function attribute, x86
-@item 3dnowa
-@itemx no-3dnowa
-Enable/disable the generation of the enhanced 3DNow!@: instructions.
+@cindex @code{target("sse2")} function attribute, x86
+@item sse2
+@itemx no-sse2
+Enable/disable the generation of the SSE2 instructions.
-@cindex @code{target("abm")} function attribute, x86
-@item abm
-@itemx no-abm
-Enable/disable the generation of the advanced bit instructions.
+@cindex @code{target("sse3")} function attribute, x86
+@item sse3
+@itemx no-sse3
+Enable/disable the generation of the SSE3 instructions.
-@cindex @code{target("adx")} function attribute, x86
-@item adx
-@itemx no-adx
-Enable/disable the generation of the ADX instructions.
+@cindex @code{target("sse4")} function attribute, x86
+@item sse4
+@itemx no-sse4
+Enable/disable the generation of the SSE4 instructions (both SSE4.1
+and SSE4.2).
-@cindex @code{target("aes")} function attribute, x86
-@item aes
-@itemx no-aes
-Enable/disable the generation of the AES instructions.
+@cindex @code{target("sse4.1")} function attribute, x86
+@item sse4.1
+@itemx no-sse4.1
+Enable/disable the generation of the SSE4.1 instructions.
-@cindex @code{target("avx")} function attribute, x86
-@item avx
-@itemx no-avx
-Enable/disable the generation of the AVX instructions.
+@cindex @code{target("sse4.2")} function attribute, x86
+@item sse4.2
+@itemx no-sse4.2
+Enable/disable the generation of the SSE4.2 instructions.
-@cindex @code{target("avx2")} function attribute, x86
-@item avx2
-@itemx no-avx2
-Enable/disable the generation of the AVX2 instructions.
+@cindex @code{target("sse4a")} function attribute, x86
+@item sse4a
+@itemx no-sse4a
+Enable/disable the generation of the SSE4A instructions.
-@cindex @code{target("avx512bitalg")} function attribute, x86
-@item avx512bitalg
-@itemx no-avx512bitalg
-Enable/disable the generation of the AVX512BITALG instructions.
+@cindex @code{target("ssse3")} function attribute, x86
+@item ssse3
+@itemx no-ssse3
+Enable/disable the generation of the SSSE3 instructions.
-@cindex @code{target("avx512bw")} function attribute, x86
-@item avx512bw
-@itemx no-avx512bw
-Enable/disable the generation of the AVX512BW instructions.
+@cindex @code{target("tbm")} function attribute, x86
+@item tbm
+@itemx no-tbm
+Enable/disable the generation of the TBM instructions.
-@cindex @code{target("avx512cd")} function attribute, x86
-@item avx512cd
-@itemx no-avx512cd
-Enable/disable the generation of the AVX512CD instructions.
+@cindex @code{target("vaes")} function attribute, x86
+@item vaes
+@itemx no-vaes
+Enable/disable the generation of the VAES instructions.
-@cindex @code{target("avx512dq")} function attribute, x86
-@item avx512dq
-@itemx no-avx512dq
-Enable/disable the generation of the AVX512DQ instructions.
+@cindex @code{target("vpclmulqdq")} function attribute, x86
+@item vpclmulqdq
+@itemx no-vpclmulqdq
+Enable/disable the generation of the VPCLMULQDQ instructions.
-@cindex @code{target("avx512er")} function attribute, x86
-@item avx512er
-@itemx no-avx512er
-Enable/disable the generation of the AVX512ER instructions.
+@cindex @code{target("waitpkg")} function attribute, x86
+@item waitpkg
+@itemx no-waitpkg
+Enable/disable the generation of the WAITPKG instructions.
-@cindex @code{target("avx512f")} function attribute, x86
-@item avx512f
-@itemx no-avx512f
-Enable/disable the generation of the AVX512F instructions.
+@cindex @code{target("wbnoinvd")} function attribute, x86
+@item wbnoinvd
+@itemx no-wbnoinvd
+Enable/disable the generation of the WBNOINVD instructions.
-@cindex @code{target("avx512ifma")} function attribute, x86
-@item avx512ifma
-@itemx no-avx512ifma
-Enable/disable the generation of the AVX512IFMA instructions.
+@cindex @code{target("xop")} function attribute, x86
+@item xop
+@itemx no-xop
+Enable/disable the generation of the XOP instructions.
-@cindex @code{target("avx512vbmi")} function attribute, x86
-@item avx512vbmi
-@itemx no-avx512vbmi
-Enable/disable the generation of the AVX512VBMI instructions.
+@cindex @code{target("xsave")} function attribute, x86
+@item xsave
+@itemx no-xsave
+Enable/disable the generation of the XSAVE instructions.
-@cindex @code{target("avx512vbmi2")} function attribute, x86
-@item avx512vbmi2
-@itemx no-avx512vbmi2
-Enable/disable the generation of the AVX512VBMI2 instructions.
-
-@cindex @code{target("avx512vl")} function attribute, x86
-@item avx512vl
-@itemx no-avx512vl
-Enable/disable the generation of the AVX512VL instructions.
+@cindex @code{target("xsavec")} function attribute, x86
+@item xsavec
+@itemx no-xsavec
+Enable/disable the generation of the XSAVEC instructions.
-@cindex @code{target("avx512vnni")} function attribute, x86
-@item avx512vnni
-@itemx no-avx512vnni
-Enable/disable the generation of the AVX512VNNI instructions.
+@cindex @code{target("xsaveopt")} function attribute, x86
+@item xsaveopt
+@itemx no-xsaveopt
+Enable/disable the generation of the XSAVEOPT instructions.
-@cindex @code{target("avx512vpopcntdq")} function attribute, x86
-@item avx512vpopcntdq
-@itemx no-avx512vpopcntdq
-Enable/disable the generation of the AVX512VPOPCNTDQ instructions.
+@cindex @code{target("xsaves")} function attribute, x86
+@item xsaves
+@itemx no-xsaves
+Enable/disable the generation of the XSAVES instructions.
-@cindex @code{target("bmi")} function attribute, x86
-@item bmi
-@itemx no-bmi
-Enable/disable the generation of the BMI instructions.
+@cindex @code{target("amx-tile")} function attribute, x86
+@item amx-tile
+@itemx no-amx-tile
+Enable/disable the generation of the AMX-TILE instructions.
-@cindex @code{target("bmi2")} function attribute, x86
-@item bmi2
-@itemx no-bmi2
-Enable/disable the generation of the BMI2 instructions.
+@cindex @code{target("amx-int8")} function attribute, x86
+@item amx-int8
+@itemx no-amx-int8
+Enable/disable the generation of the AMX-INT8 instructions.
-@cindex @code{target("cldemote")} function attribute, x86
-@item cldemote
-@itemx no-cldemote
-Enable/disable the generation of the CLDEMOTE instructions.
+@cindex @code{target("amx-bf16")} function attribute, x86
+@item amx-bf16
+@itemx no-amx-bf16
+Enable/disable the generation of the AMX-BF16 instructions.
-@cindex @code{target("clflushopt")} function attribute, x86
-@item clflushopt
-@itemx no-clflushopt
-Enable/disable the generation of the CLFLUSHOPT instructions.
+@cindex @code{target("uintr")} function attribute, x86
+@item uintr
+@itemx no-uintr
+Enable/disable the generation of the UINTR instructions.
-@cindex @code{target("clwb")} function attribute, x86
-@item clwb
-@itemx no-clwb
-Enable/disable the generation of the CLWB instructions.
+@cindex @code{target("hreset")} function attribute, x86
+@item hreset
+@itemx no-hreset
+Enable/disable the generation of the HRESET instruction.
-@cindex @code{target("clzero")} function attribute, x86
-@item clzero
-@itemx no-clzero
-Enable/disable the generation of the CLZERO instructions.
+@cindex @code{target("kl")} function attribute, x86
+@item kl
+@itemx no-kl
+Enable/disable the generation of the KEYLOCKER instructions.
-@cindex @code{target("crc32")} function attribute, x86
-@item crc32
-@itemx no-crc32
-Enable/disable the generation of the CRC32 instructions.
+@cindex @code{target("widekl")} function attribute, x86
+@item widekl
+@itemx no-widekl
+Enable/disable the generation of the WIDEKL instructions.
-@cindex @code{target("cx16")} function attribute, x86
-@item cx16
-@itemx no-cx16
-Enable/disable the generation of the CMPXCHG16B instructions.
+@cindex @code{target("avxvnni")} function attribute, x86
+@item avxvnni
+@itemx no-avxvnni
+Enable/disable the generation of the AVXVNNI instructions.
-@cindex @code{target("default")} function attribute, x86
-@item default
-@xref{Function Multiversioning}, where it is used to specify the
-default function version.
+@cindex @code{target("avxifma")} function attribute, x86
+@item avxifma
+@itemx no-avxifma
+Enable/disable the generation of the AVXIFMA instructions.
-@cindex @code{target("f16c")} function attribute, x86
-@item f16c
-@itemx no-f16c
-Enable/disable the generation of the F16C instructions.
+@cindex @code{target("avxvnniint8")} function attribute, x86
+@item avxvnniint8
+@itemx no-avxvnniint8
+Enable/disable the generation of the AVXVNNIINT8 instructions.
-@cindex @code{target("fma")} function attribute, x86
-@item fma
-@itemx no-fma
-Enable/disable the generation of the FMA instructions.
+@cindex @code{target("avxneconvert")} function attribute, x86
+@item avxneconvert
+@itemx no-avxneconvert
+Enable/disable the generation of the AVXNECONVERT instructions.
-@cindex @code{target("fma4")} function attribute, x86
-@item fma4
-@itemx no-fma4
-Enable/disable the generation of the FMA4 instructions.
+@cindex @code{target("cmpccxadd")} function attribute, x86
+@item cmpccxadd
+@itemx no-cmpccxadd
+Enable/disable the generation of the CMPccXADD instructions.
-@cindex @code{target("fsgsbase")} function attribute, x86
-@item fsgsbase
-@itemx no-fsgsbase
-Enable/disable the generation of the FSGSBASE instructions.
+@cindex @code{target("amx-fp16")} function attribute, x86
+@item amx-fp16
+@itemx no-amx-fp16
+Enable/disable the generation of the AMX-FP16 instructions.
-@cindex @code{target("fxsr")} function attribute, x86
-@item fxsr
-@itemx no-fxsr
-Enable/disable the generation of the FXSR instructions.
+@cindex @code{target("prefetchi")} function attribute, x86
+@item prefetchi
+@itemx no-prefetchi
+Enable/disable the generation of the PREFETCHI instructions.
-@cindex @code{target("gfni")} function attribute, x86
-@item gfni
-@itemx no-gfni
-Enable/disable the generation of the GFNI instructions.
+@cindex @code{target("raoint")} function attribute, x86
+@item raoint
+@itemx no-raoint
+Enable/disable the generation of the RAOINT instructions.
-@cindex @code{target("hle")} function attribute, x86
-@item hle
-@itemx no-hle
-Enable/disable the generation of the HLE instruction prefixes.
+@cindex @code{target("amx-complex")} function attribute, x86
+@item amx-complex
+@itemx no-amx-complex
+Enable/disable the generation of the AMX-COMPLEX instructions.
-@cindex @code{target("lwp")} function attribute, x86
-@item lwp
-@itemx no-lwp
-Enable/disable the generation of the LWP instructions.
+@cindex @code{target("avxvnniint16")} function attribute, x86
+@item avxvnniint16
+@itemx no-avxvnniint16
+Enable/disable the generation of the AVXVNNIINT16 instructions.
-@cindex @code{target("lzcnt")} function attribute, x86
-@item lzcnt
-@itemx no-lzcnt
-Enable/disable the generation of the LZCNT instructions.
+@cindex @code{target("sm3")} function attribute, x86
+@item sm3
+@itemx no-sm3
+Enable/disable the generation of the SM3 instructions.
-@cindex @code{target("mmx")} function attribute, x86
-@item mmx
-@itemx no-mmx
-Enable/disable the generation of the MMX instructions.
+@cindex @code{target("sha512")} function attribute, x86
+@item sha512
+@itemx no-sha512
+Enable/disable the generation of the SHA512 instructions.
-@cindex @code{target("movbe")} function attribute, x86
-@item movbe
-@itemx no-movbe
-Enable/disable the generation of the MOVBE instructions.
+@cindex @code{target("sm4")} function attribute, x86
+@item sm4
+@itemx no-sm4
+Enable/disable the generation of the SM4 instructions.
-@cindex @code{target("movdir64b")} function attribute, x86
-@item movdir64b
-@itemx no-movdir64b
-Enable/disable the generation of the MOVDIR64B instructions.
+@cindex @code{target("usermsr")} function attribute, x86
+@item usermsr
+@itemx no-usermsr
+Enable/disable the generation of the USER_MSR instructions.
-@cindex @code{target("movdiri")} function attribute, x86
-@item movdiri
-@itemx no-movdiri
-Enable/disable the generation of the MOVDIRI instructions.
+@cindex @code{target("apxf")} function attribute, x86
+@item apxf
+@itemx no-apxf
+Enable/disable the generation of the APX features, including
+EGPR, PUSH2POP2, NDD and PPX.
-@cindex @code{target("mwait")} function attribute, x86
-@item mwait
-@itemx no-mwait
-Enable/disable the generation of the MWAIT and MONITOR instructions.
+@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("mwaitx")} function attribute, x86
-@item mwaitx
-@itemx no-mwaitx
-Enable/disable the generation of the MWAITX 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.
-@cindex @code{target("pclmul")} function attribute, x86
-@item pclmul
-@itemx no-pclmul
-Enable/disable the generation of the PCLMUL instructions.
+@cindex @code{target("avx10.2")} function attribute, x86
+@item avx10.2
+@itemx no-avx10.2
+Enable the generation of the AVX10.2 instructions with 512 bit support.
+Disable the generation of the AVX10.2 instructions.
-@cindex @code{target("pconfig")} function attribute, x86
-@item pconfig
-@itemx no-pconfig
-Enable/disable the generation of the PCONFIG instructions.
+@cindex @code{target("avx10.2-256")} function attribute, x86
+@item avx10.2-256
+Enable the generation of the AVX10.2 instructions with 256 bit support.
-@cindex @code{target("pku")} function attribute, x86
-@item pku
-@itemx no-pku
-Enable/disable the generation of the PKU instructions.
+@cindex @code{target("avx10.2-512")} function attribute, x86
+@item avx10.2-512
+Enable the generation of the AVX10.2 instructions with 512 bit support.
-@cindex @code{target("popcnt")} function attribute, x86
-@item popcnt
-@itemx no-popcnt
-Enable/disable the generation of the POPCNT instruction.
+@cindex @code{target("amx-avx512")} function attribute, x86
+@item amx-avx512
+@itemx no-amx-avx512
+Enable/disable the generation of the AMX-AVX512 instructions.
-@cindex @code{target("prfchw")} function attribute, x86
-@item prfchw
-@itemx no-prfchw
-Enable/disable the generation of the PREFETCHW instruction.
+@cindex @code{target("amx-tf32")} function attribute, x86
+@item amx-tf32
+@itemx no-amx-tf32
+Enable/disable the generation of the AMX-TF32 instructions.
-@cindex @code{target("ptwrite")} function attribute, x86
-@item ptwrite
-@itemx no-ptwrite
-Enable/disable the generation of the PTWRITE instructions.
+@cindex @code{target("amx-transpose")} function attribute, x86
+@item amx-transpose
+@itemx no-amx-transpose
+Enable/disable the generation of the AMX-TRANSPOSE instructions.
-@cindex @code{target("rdpid")} function attribute, x86
-@item rdpid
-@itemx no-rdpid
-Enable/disable the generation of the RDPID instructions.
+@cindex @code{target("amx-fp8")} function attribute, x86
+@item amx-fp8
+@itemx no-amx-fp8
+Enable/disable the generation of the AMX-FP8 instructions.
-@cindex @code{target("rdrnd")} function attribute, x86
-@item rdrnd
-@itemx no-rdrnd
-Enable/disable the generation of the RDRND instructions.
+@cindex @code{target("movrs")} function attribute, x86
+@item movrs
+@itemx no-movrs
+Enable/disable the generation of the MOVRS instructions.
-@cindex @code{target("rdseed")} function attribute, x86
-@item rdseed
-@itemx no-rdseed
-Enable/disable the generation of the RDSEED instructions.
+@cindex @code{target("amx-movrs")} function attribute, x86
+@item amx-movrs
+@itemx no-amx-movrs
+Enable/disable the generation of the AMX-MOVRS instructions.
-@cindex @code{target("rtm")} function attribute, x86
-@item rtm
-@itemx no-rtm
-Enable/disable the generation of the RTM instructions.
+@cindex @code{target("cld")} function attribute, x86
+@item cld
+@itemx no-cld
+Enable/disable the generation of the CLD before string moves.
-@cindex @code{target("sahf")} function attribute, x86
-@item sahf
-@itemx no-sahf
-Enable/disable the generation of the SAHF instructions.
+@cindex @code{target("fancy-math-387")} function attribute, x86
+@item fancy-math-387
+@itemx no-fancy-math-387
+Enable/disable the generation of the @code{sin}, @code{cos}, and
+@code{sqrt} instructions on the 387 floating-point unit.
-@cindex @code{target("sgx")} function attribute, x86
-@item sgx
-@itemx no-sgx
-Enable/disable the generation of the SGX instructions.
+@cindex @code{target("ieee-fp")} function attribute, x86
+@item ieee-fp
+@itemx no-ieee-fp
+Enable/disable the generation of floating point that depends on IEEE arithmetic.
-@cindex @code{target("sha")} function attribute, x86
-@item sha
-@itemx no-sha
-Enable/disable the generation of the SHA instructions.
+@cindex @code{target("inline-all-stringops")} function attribute, x86
+@item inline-all-stringops
+@itemx no-inline-all-stringops
+Enable/disable inlining of string operations.
-@cindex @code{target("shstk")} function attribute, x86
-@item shstk
-@itemx no-shstk
-Enable/disable the shadow stack built-in functions from CET.
+@cindex @code{target("inline-stringops-dynamically")} function attribute, x86
+@item inline-stringops-dynamically
+@itemx no-inline-stringops-dynamically
+Enable/disable the generation of the inline code to do small string
+operations and calling the library routines for large operations.
-@cindex @code{target("sse")} function attribute, x86
-@item sse
-@itemx no-sse
-Enable/disable the generation of the SSE instructions.
+@cindex @code{target("align-stringops")} function attribute, x86
+@item align-stringops
+@itemx no-align-stringops
+Do/do not align destination of inlined string operations.
-@cindex @code{target("sse2")} function attribute, x86
-@item sse2
-@itemx no-sse2
-Enable/disable the generation of the SSE2 instructions.
+@cindex @code{target("recip")} function attribute, x86
+@item recip
+@itemx no-recip
+Enable/disable the generation of RCPSS, RCPPS, RSQRTSS and RSQRTPS
+instructions followed an additional Newton-Raphson step instead of
+doing a floating-point division.
-@cindex @code{target("sse3")} function attribute, x86
-@item sse3
-@itemx no-sse3
-Enable/disable the generation of the SSE3 instructions.
+@cindex @code{target("general-regs-only")} function attribute, x86
+@item general-regs-only
+Generate code which uses only the general registers.
-@cindex @code{target("sse4")} function attribute, x86
-@item sse4
-@itemx no-sse4
-Enable/disable the generation of the SSE4 instructions (both SSE4.1
-and SSE4.2).
+@cindex @code{target("arch=@var{ARCH}")} function attribute, x86
+@item arch=@var{ARCH}
+Specify the architecture to generate code for in compiling the function.
-@cindex @code{target("sse4.1")} function attribute, x86
-@item sse4.1
-@itemx no-sse4.1
-Enable/disable the generation of the SSE4.1 instructions.
+@cindex @code{target("tune=@var{TUNE}")} function attribute, x86
+@item tune=@var{TUNE}
+Specify the architecture to tune for in compiling the function.
-@cindex @code{target("sse4.2")} function attribute, x86
-@item sse4.2
-@itemx no-sse4.2
-Enable/disable the generation of the SSE4.2 instructions.
+@cindex @code{target("fpmath=@var{FPMATH}")} function attribute, x86
+@item fpmath=@var{FPMATH}
+Specify which floating-point unit to use. You must specify the
+@code{target("fpmath=sse,387")} option as
+@code{target("fpmath=sse+387")} because the comma would separate
+different options.
-@cindex @code{target("sse4a")} function attribute, x86
-@item sse4a
-@itemx no-sse4a
-Enable/disable the generation of the SSE4A instructions.
+@cindex @code{prefer-vector-width} function attribute, x86
+@item prefer-vector-width=@var{OPT}
+On x86 targets, the @code{prefer-vector-width} attribute informs the
+compiler to use @var{OPT}-bit vector width in instructions
+instead of the default on the selected platform.
-@cindex @code{target("ssse3")} function attribute, x86
-@item ssse3
-@itemx no-ssse3
-Enable/disable the generation of the SSSE3 instructions.
+Valid @var{OPT} values are:
-@cindex @code{target("tbm")} function attribute, x86
-@item tbm
-@itemx no-tbm
-Enable/disable the generation of the TBM instructions.
+@table @samp
+@item none
+No extra limitations applied to GCC other than defined by the selected platform.
-@cindex @code{target("vaes")} function attribute, x86
-@item vaes
-@itemx no-vaes
-Enable/disable the generation of the VAES instructions.
+@item 128
+Prefer 128-bit vector width for instructions.
-@cindex @code{target("vpclmulqdq")} function attribute, x86
-@item vpclmulqdq
-@itemx no-vpclmulqdq
-Enable/disable the generation of the VPCLMULQDQ instructions.
+@item 256
+Prefer 256-bit vector width for instructions.
-@cindex @code{target("waitpkg")} function attribute, x86
-@item waitpkg
-@itemx no-waitpkg
-Enable/disable the generation of the WAITPKG instructions.
+@item 512
+Prefer 512-bit vector width for instructions.
+@end table
-@cindex @code{target("wbnoinvd")} function attribute, x86
-@item wbnoinvd
-@itemx no-wbnoinvd
-Enable/disable the generation of the WBNOINVD instructions.
+@end table
-@cindex @code{target("xop")} function attribute, x86
-@item xop
-@itemx no-xop
-Enable/disable the generation of the XOP instructions.
+@cindex @code{indirect_branch} function attribute, x86
+@item indirect_branch("@var{choice}")
+On x86 targets, the @code{indirect_branch} attribute causes the compiler
+to convert indirect call and jump with @var{choice}. @samp{keep}
+keeps indirect call and jump unmodified. @samp{thunk} converts indirect
+call and jump to call and return thunk. @samp{thunk-inline} converts
+indirect call and jump to inlined call and return thunk.
+@samp{thunk-extern} converts indirect call and jump to external call
+and return thunk provided in a separate object file.
-@cindex @code{target("xsave")} function attribute, x86
-@item xsave
-@itemx no-xsave
-Enable/disable the generation of the XSAVE instructions.
+@cindex @code{function_return} function attribute, x86
+@item function_return("@var{choice}")
+On x86 targets, the @code{function_return} attribute causes the compiler
+to convert function return with @var{choice}. @samp{keep} keeps function
+return unmodified. @samp{thunk} converts function return to call and
+return thunk. @samp{thunk-inline} converts function return to inlined
+call and return thunk. @samp{thunk-extern} converts function return to
+external call and return thunk provided in a separate object file.
-@cindex @code{target("xsavec")} function attribute, x86
-@item xsavec
-@itemx no-xsavec
-Enable/disable the generation of the XSAVEC instructions.
+@cindex @code{nocf_check} function attribute
+@item nocf_check
+The @code{nocf_check} attribute on a function is used to inform the
+compiler that the function's prologue should not be instrumented when
+compiled with the @option{-fcf-protection=branch} option. The
+compiler assumes that the function's address is a valid target for a
+control-flow transfer.
-@cindex @code{target("xsaveopt")} function attribute, x86
-@item xsaveopt
-@itemx no-xsaveopt
-Enable/disable the generation of the XSAVEOPT instructions.
+The @code{nocf_check} attribute on a type of pointer to function is
+used to inform the compiler that a call through the pointer should
+not be instrumented when compiled with the
+@option{-fcf-protection=branch} option. The compiler assumes
+that the function's address from the pointer is a valid target for
+a control-flow transfer. A direct function call through a function
+name is assumed to be a safe call thus direct calls are not
+instrumented by the compiler.
-@cindex @code{target("xsaves")} function attribute, x86
-@item xsaves
-@itemx no-xsaves
-Enable/disable the generation of the XSAVES instructions.
+The @code{nocf_check} attribute is applied to an object's type.
+In case of assignment of a function address or a function pointer to
+another pointer, the attribute is not carried over from the right-hand
+object's type; the type of left-hand object stays unchanged. The
+compiler checks for @code{nocf_check} attribute mismatch and reports
+a warning in case of mismatch.
-@cindex @code{target("amx-tile")} function attribute, x86
-@item amx-tile
-@itemx no-amx-tile
-Enable/disable the generation of the AMX-TILE instructions.
+@smallexample
+@{
+int foo (void) __attribute__(nocf_check);
+void (*foo1)(void) __attribute__(nocf_check);
+void (*foo2)(void);
-@cindex @code{target("amx-int8")} function attribute, x86
-@item amx-int8
-@itemx no-amx-int8
-Enable/disable the generation of the AMX-INT8 instructions.
+/* foo's address is assumed to be valid. */
+int
+foo (void)
-@cindex @code{target("amx-bf16")} function attribute, x86
-@item amx-bf16
-@itemx no-amx-bf16
-Enable/disable the generation of the AMX-BF16 instructions.
+ /* This call site is not checked for control-flow
+ validity. */
+ (*foo1)();
-@cindex @code{target("uintr")} function attribute, x86
-@item uintr
-@itemx no-uintr
-Enable/disable the generation of the UINTR instructions.
-
-@cindex @code{target("hreset")} function attribute, x86
-@item hreset
-@itemx no-hreset
-Enable/disable the generation of the HRESET instruction.
+ /* A warning is issued about attribute mismatch. */
+ foo1 = foo2;
-@cindex @code{target("kl")} function attribute, x86
-@item kl
-@itemx no-kl
-Enable/disable the generation of the KEYLOCKER instructions.
+ /* This call site is still not checked. */
+ (*foo1)();
-@cindex @code{target("widekl")} function attribute, x86
-@item widekl
-@itemx no-widekl
-Enable/disable the generation of the WIDEKL instructions.
+ /* This call site is checked. */
+ (*foo2)();
-@cindex @code{target("avxvnni")} function attribute, x86
-@item avxvnni
-@itemx no-avxvnni
-Enable/disable the generation of the AVXVNNI instructions.
+ /* A warning is issued about attribute mismatch. */
+ foo2 = foo1;
-@cindex @code{target("avxifma")} function attribute, x86
-@item avxifma
-@itemx no-avxifma
-Enable/disable the generation of the AVXIFMA instructions.
+ /* This call site is still checked. */
+ (*foo2)();
-@cindex @code{target("avxvnniint8")} function attribute, x86
-@item avxvnniint8
-@itemx no-avxvnniint8
-Enable/disable the generation of the AVXVNNIINT8 instructions.
+ return 0;
+@}
+@end smallexample
-@cindex @code{target("avxneconvert")} function attribute, x86
-@item avxneconvert
-@itemx no-avxneconvert
-Enable/disable the generation of the AVXNECONVERT instructions.
+@cindex @code{cf_check} function attribute, x86
+@item cf_check
-@cindex @code{target("cmpccxadd")} function attribute, x86
-@item cmpccxadd
-@itemx no-cmpccxadd
-Enable/disable the generation of the CMPccXADD instructions.
+The @code{cf_check} attribute on a function is used to inform the
+compiler that ENDBR instruction should be placed at the function
+entry when @option{-fcf-protection=branch} is enabled.
-@cindex @code{target("amx-fp16")} function attribute, x86
-@item amx-fp16
-@itemx no-amx-fp16
-Enable/disable the generation of the AMX-FP16 instructions.
+@cindex @code{indirect_return} function attribute, x86
+@item indirect_return
-@cindex @code{target("prefetchi")} function attribute, x86
-@item prefetchi
-@itemx no-prefetchi
-Enable/disable the generation of the PREFETCHI instructions.
+The @code{indirect_return} attribute can be applied to a function,
+as well as variable or type of function pointer to inform the
+compiler that the function may return via indirect branch.
-@cindex @code{target("raoint")} function attribute, x86
-@item raoint
-@itemx no-raoint
-Enable/disable the generation of the RAOINT instructions.
+@cindex @code{fentry_name} function attribute, x86
+@item fentry_name("@var{name}")
+On x86 targets, the @code{fentry_name} attribute sets the function to
+call on function entry when function instrumentation is enabled
+with @option{-pg -mfentry}. When @var{name} is nop then a 5 byte
+nop sequence is generated.
-@cindex @code{target("amx-complex")} function attribute, x86
-@item amx-complex
-@itemx no-amx-complex
-Enable/disable the generation of the AMX-COMPLEX instructions.
+@cindex @code{fentry_section} function attribute, x86
+@item fentry_section("@var{name}")
+On x86 targets, the @code{fentry_section} attribute sets the name
+of the section to record function entry instrumentation calls in when
+enabled with @option{-pg -mrecord-mcount}
-@cindex @code{target("avxvnniint16")} function attribute, x86
-@item avxvnniint16
-@itemx no-avxvnniint16
-Enable/disable the generation of the AVXVNNIINT16 instructions.
+@cindex @code{nodirect_extern_access} function attribute
+@opindex mno-direct-extern-access
+@item nodirect_extern_access
+This attribute, attached to a global variable or function, is the
+counterpart to option @option{-mno-direct-extern-access}.
-@cindex @code{target("sm3")} function attribute, x86
-@item sm3
-@itemx no-sm3
-Enable/disable the generation of the SM3 instructions.
+@end table
-@cindex @code{target("sha512")} function attribute, x86
-@item sha512
-@itemx no-sha512
-Enable/disable the generation of the SHA512 instructions.
+@subsubsection 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
+a function declared with @code{target("sse3")} can inline a function
+with @code{target("sse2")}, since @code{-msse3} implies @code{-msse2}.
-@cindex @code{target("sm4")} function attribute, x86
-@item sm4
-@itemx no-sm4
-Enable/disable the generation of the SM4 instructions.
+Besides the basic rule, when a function specifies
+@code{target("arch=@var{ARCH}")} or @code{target("tune=@var{TUNE}")}
+attribute, the inlining rule will be different. It allows inlining of
+a function with default @option{-march=x86-64} and
+@option{-mtune=generic} specified, or a function that has a subset
+of ISA features and marked with always_inline.
-@cindex @code{target("usermsr")} function attribute, x86
-@item usermsr
-@itemx no-usermsr
-Enable/disable the generation of the USER_MSR instructions.
+@node Xstormy16 Function Attributes
+@subsection Xstormy16 Function Attributes
-@cindex @code{target("apxf")} function attribute, x86
-@item apxf
-@itemx no-apxf
-Enable/disable the generation of the APX features, including
-EGPR, PUSH2POP2, NDD and PPX.
+These function attributes are supported by the Xstormy16 back end:
-@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.
+@table @code
+@cindex @code{interrupt} function attribute, Xstormy16
+@item interrupt
+Use this attribute to indicate
+that the specified function is an interrupt handler. The compiler generates
+function entry and exit sequences suitable for use in an interrupt handler
+when this attribute is present.
+@end table
-@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.
+@node Variable Attributes
+@section Specifying Attributes of Variables
+@cindex attribute of variables
+@cindex variable attributes
-@cindex @code{target("avx10.2")} function attribute, x86
-@item avx10.2
-@itemx no-avx10.2
-Enable the generation of the AVX10.2 instructions with 512 bit support.
-Disable the generation of the AVX10.2 instructions.
+You can use attributes to specify special properties
+of variables, function parameters, or structure, union, and, in C++, class
+members. Some attributes are currently
+defined generically for variables. Other attributes are defined for
+variables on particular target systems. Other attributes are available
+for functions (@pxref{Function Attributes}), labels (@pxref{Label Attributes}),
+enumerators (@pxref{Enumerator Attributes}), statements
+(@pxref{Statement Attributes}), and for types (@pxref{Type Attributes}).
+Other front ends might define more attributes
+(@pxref{C++ Extensions,,Extensions to the C++ Language}).
-@cindex @code{target("avx10.2-256")} function attribute, x86
-@item avx10.2-256
-Enable the generation of the AVX10.2 instructions with 256 bit support.
+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::} prefix on attribute names. Note that the exact rules for
+placement of attributes in your source code are different depending on
+which syntax you use. @xref{Attribute Syntax}, for details.
-@cindex @code{target("avx10.2-512")} function attribute, x86
-@item avx10.2-512
-Enable the generation of the AVX10.2 instructions with 512 bit support.
+@menu
+* Common Variable Attributes::
+* ARC Variable Attributes::
+* AVR Variable Attributes::
+* Blackfin Variable Attributes::
+* H8/300 Variable Attributes::
+* IA-64 Variable Attributes::
+* LoongArch Variable Attributes::
+* M32R/D Variable Attributes::
+* Microsoft Windows Variable Attributes::
+* MSP430 Variable Attributes::
+* Nvidia PTX Variable Attributes::
+* PowerPC Variable Attributes::
+* RL78 Variable Attributes::
+* V850 Variable Attributes::
+* x86 Variable Attributes::
+* Xstormy16 Variable Attributes::
+@end menu
-@cindex @code{target("amx-avx512")} function attribute, x86
-@item amx-avx512
-@itemx no-amx-avx512
-Enable/disable the generation of the AMX-AVX512 instructions.
+@node Common Variable Attributes
+@subsection Common Variable Attributes
-@cindex @code{target("amx-tf32")} function attribute, x86
-@item amx-tf32
-@itemx no-amx-tf32
-Enable/disable the generation of the AMX-TF32 instructions.
+The following attributes are supported on most targets.
-@cindex @code{target("amx-transpose")} function attribute, x86
-@item amx-transpose
-@itemx no-amx-transpose
-Enable/disable the generation of the AMX-TRANSPOSE instructions.
+@table @code
+@c Keep this table alphabetized by attribute name. Treat _ as space.
-@cindex @code{target("amx-fp8")} function attribute, x86
-@item amx-fp8
-@itemx no-amx-fp8
-Enable/disable the generation of the AMX-FP8 instructions.
+@cindex @code{alias} variable attribute
+@item alias ("@var{target}")
+The @code{alias} variable attribute causes the declaration to be emitted
+as an alias for another symbol known as an @dfn{alias target}. Except
+for top-level qualifiers the alias target must have the same type as
+the alias. For instance, the following
-@cindex @code{target("movrs")} function attribute, x86
-@item movrs
-@itemx no-movrs
-Enable/disable the generation of the MOVRS instructions.
+@smallexample
+int var_target;
+extern int __attribute__ ((alias ("var_target"))) var_alias;
+@end smallexample
-@cindex @code{target("amx-movrs")} function attribute, x86
-@item amx-movrs
-@itemx no-amx-movrs
-Enable/disable the generation of the AMX-MOVRS instructions.
+@noindent
+defines @code{var_alias} to be an alias for the @code{var_target} variable.
-@cindex @code{target("cld")} function attribute, x86
-@item cld
-@itemx no-cld
-Enable/disable the generation of the CLD before string moves.
+It is an error if the alias target is not defined in the same translation
+unit as the alias.
-@cindex @code{target("fancy-math-387")} function attribute, x86
-@item fancy-math-387
-@itemx no-fancy-math-387
-Enable/disable the generation of the @code{sin}, @code{cos}, and
-@code{sqrt} instructions on the 387 floating-point unit.
+Note that in the absence of the attribute GCC assumes that distinct
+declarations with external linkage denote distinct objects. Using both
+the alias and the alias target to access the same object is undefined
+in a translation unit without a declaration of the alias with the attribute.
-@cindex @code{target("ieee-fp")} function attribute, x86
-@item ieee-fp
-@itemx no-ieee-fp
-Enable/disable the generation of floating point that depends on IEEE arithmetic.
-
-@cindex @code{target("inline-all-stringops")} function attribute, x86
-@item inline-all-stringops
-@itemx no-inline-all-stringops
-Enable/disable inlining of string operations.
+This attribute requires assembler and object file support, and may not be
+available on all targets.
-@cindex @code{target("inline-stringops-dynamically")} function attribute, x86
-@item inline-stringops-dynamically
-@itemx no-inline-stringops-dynamically
-Enable/disable the generation of the inline code to do small string
-operations and calling the library routines for large operations.
+@cindex @code{aligned} variable attribute
+@item aligned
+@itemx aligned (@var{alignment})
+The @code{aligned} attribute specifies a minimum alignment for the variable
+or structure field, measured in bytes. When specified, @var{alignment} must
+be an integer constant power of 2. Specifying no @var{alignment} argument
+implies the maximum alignment for the target, which is often, but by no
+means always, 8 or 16 bytes.
-@cindex @code{target("align-stringops")} function attribute, x86
-@item align-stringops
-@itemx no-align-stringops
-Do/do not align destination of inlined string operations.
+For example, the declaration:
-@cindex @code{target("recip")} function attribute, x86
-@item recip
-@itemx no-recip
-Enable/disable the generation of RCPSS, RCPPS, RSQRTSS and RSQRTPS
-instructions followed an additional Newton-Raphson step instead of
-doing a floating-point division.
+@smallexample
+int x __attribute__ ((aligned (16))) = 0;
+@end smallexample
-@cindex @code{target("general-regs-only")} function attribute, x86
-@item general-regs-only
-Generate code which uses only the general registers.
+@noindent
+causes the compiler to allocate the global variable @code{x} on a
+16-byte boundary. On a 68040, this could be used in conjunction with
+an @code{asm} expression to access the @code{move16} instruction which
+requires 16-byte aligned operands.
-@cindex @code{target("arch=@var{ARCH}")} function attribute, x86
-@item arch=@var{ARCH}
-Specify the architecture to generate code for in compiling the function.
+You can also specify the alignment of structure fields. For example, to
+create a double-word aligned @code{int} pair, you could write:
-@cindex @code{target("tune=@var{TUNE}")} function attribute, x86
-@item tune=@var{TUNE}
-Specify the architecture to tune for in compiling the function.
+@smallexample
+struct foo @{ int x[2] __attribute__ ((aligned (8))); @};
+@end smallexample
-@cindex @code{target("fpmath=@var{FPMATH}")} function attribute, x86
-@item fpmath=@var{FPMATH}
-Specify which floating-point unit to use. You must specify the
-@code{target("fpmath=sse,387")} option as
-@code{target("fpmath=sse+387")} because the comma would separate
-different options.
+@noindent
+This is an alternative to creating a union with a @code{double} member,
+which forces the union to be double-word aligned.
-@cindex @code{prefer-vector-width} function attribute, x86
-@item prefer-vector-width=@var{OPT}
-On x86 targets, the @code{prefer-vector-width} attribute informs the
-compiler to use @var{OPT}-bit vector width in instructions
-instead of the default on the selected platform.
+As in the preceding examples, you can explicitly specify the alignment
+(in bytes) that you wish the compiler to use for a given variable or
+structure field. Alternatively, you can leave out the alignment factor
+and just ask the compiler to align a variable or field to the
+default alignment for the target architecture you are compiling for.
+The default alignment is sufficient for all scalar types, but may not be
+enough for all vector types on a target that supports vector operations.
+The default alignment is fixed for a particular target ABI.
-Valid @var{OPT} values are:
+GCC also provides a target specific macro @code{__BIGGEST_ALIGNMENT__},
+which is the largest alignment ever used for any data type on the
+target machine you are compiling for. For example, you could write:
-@table @samp
-@item none
-No extra limitations applied to GCC other than defined by the selected platform.
+@smallexample
+short array[3] __attribute__ ((aligned (__BIGGEST_ALIGNMENT__)));
+@end smallexample
-@item 128
-Prefer 128-bit vector width for instructions.
+The compiler automatically sets the alignment for the declared
+variable or field to @code{__BIGGEST_ALIGNMENT__}. Doing this can
+often make copy operations more efficient, because the compiler can
+use whatever instructions copy the biggest chunks of memory when
+performing copies to or from the variables or fields that you have
+aligned this way. Note that the value of @code{__BIGGEST_ALIGNMENT__}
+may change depending on command-line options.
-@item 256
-Prefer 256-bit vector width for instructions.
+When used on a struct, or struct member, the @code{aligned} attribute can
+only increase the alignment; in order to decrease it, the @code{packed}
+attribute must be specified as well. When used as part of a typedef, the
+@code{aligned} attribute can both increase and decrease alignment, and
+specifying the @code{packed} attribute generates a warning.
-@item 512
-Prefer 512-bit vector width for instructions.
-@end table
+Note that the effectiveness of @code{aligned} attributes for static
+variables may be limited by inherent limitations in the system linker
+and/or object file format. On some systems, the linker is
+only able to arrange for variables to be aligned up to a certain maximum
+alignment. (For some linkers, the maximum supported alignment may
+be very very small.) If your linker is only able to align variables
+up to a maximum of 8-byte alignment, then specifying @code{aligned(16)}
+in an @code{__attribute__} still only provides you with 8-byte
+alignment. See your linker documentation for further information.
-@end table
+Stack variables are not affected by linker restrictions; GCC can properly
+align them on any target.
-@cindex @code{indirect_branch} function attribute, x86
-@item indirect_branch("@var{choice}")
-On x86 targets, the @code{indirect_branch} attribute causes the compiler
-to convert indirect call and jump with @var{choice}. @samp{keep}
-keeps indirect call and jump unmodified. @samp{thunk} converts indirect
-call and jump to call and return thunk. @samp{thunk-inline} converts
-indirect call and jump to inlined call and return thunk.
-@samp{thunk-extern} converts indirect call and jump to external call
-and return thunk provided in a separate object file.
+The @code{aligned} attribute can also be used for functions
+(@pxref{Common Function Attributes}.)
-@cindex @code{function_return} function attribute, x86
-@item function_return("@var{choice}")
-On x86 targets, the @code{function_return} attribute causes the compiler
-to convert function return with @var{choice}. @samp{keep} keeps function
-return unmodified. @samp{thunk} converts function return to call and
-return thunk. @samp{thunk-inline} converts function return to inlined
-call and return thunk. @samp{thunk-extern} converts function return to
-external call and return thunk provided in a separate object file.
+@cindex @code{counted_by} variable attribute
+@item counted_by (@var{count})
+The @code{counted_by} attribute may be attached to the C99 flexible array
+member of a structure. It indicates that the number of the elements of the
+array is given by the field "@var{count}" in the same structure as the
+flexible array member.
-@cindex @code{nocf_check} function attribute
-@item nocf_check
-The @code{nocf_check} attribute on a function is used to inform the
-compiler that the function's prologue should not be instrumented when
-compiled with the @option{-fcf-protection=branch} option. The
-compiler assumes that the function's address is a valid target for a
-control-flow transfer.
+This attribute is available only in C for now.
+In C++ this attribute is ignored.
-The @code{nocf_check} attribute on a type of pointer to function is
-used to inform the compiler that a call through the pointer should
-not be instrumented when compiled with the
-@option{-fcf-protection=branch} option. The compiler assumes
-that the function's address from the pointer is a valid target for
-a control-flow transfer. A direct function call through a function
-name is assumed to be a safe call thus direct calls are not
-instrumented by the compiler.
+GCC may use this information to improve detection of object size information
+for such structures and provide better results in compile-time diagnostics
+and runtime features like the array bound sanitizer and
+the @code{__builtin_dynamic_object_size}.
-The @code{nocf_check} attribute is applied to an object's type.
-In case of assignment of a function address or a function pointer to
-another pointer, the attribute is not carried over from the right-hand
-object's type; the type of left-hand object stays unchanged. The
-compiler checks for @code{nocf_check} attribute mismatch and reports
-a warning in case of mismatch.
+For instance, the following code:
@smallexample
-@{
-int foo (void) __attribute__(nocf_check);
-void (*foo1)(void) __attribute__(nocf_check);
-void (*foo2)(void);
+struct P @{
+ size_t count;
+ char other;
+ char array[] __attribute__ ((counted_by (count)));
+@} *p;
+@end smallexample
-/* foo's address is assumed to be valid. */
-int
-foo (void)
+@noindent
+specifies that the @code{array} is a flexible array member whose number of
+elements is given by the field @code{count} in the same structure.
- /* This call site is not checked for control-flow
- validity. */
- (*foo1)();
+The field that represents the number of the elements should have an
+integer type. Otherwise, the compiler reports an error and ignores
+the attribute.
- /* A warning is issued about attribute mismatch. */
- foo1 = foo2;
+When the field that represents the number of the elements is assigned a
+negative integer value, the compiler treats the value as zero.
- /* This call site is still not checked. */
- (*foo1)();
+An explicit @code{counted_by} annotation defines a relationship between
+two objects, @code{p->array} and @code{p->count}, and there are the
+following requirements on the relationship between this pair:
- /* This call site is checked. */
- (*foo2)();
+@itemize @bullet
+@item
+@code{p->count} must be initialized before the first reference to
+@code{p->array};
- /* A warning is issued about attribute mismatch. */
- foo2 = foo1;
+@item
+@code{p->array} has @emph{at least} @code{p->count} number of elements
+available all the time. This relationship must hold even after any of
+these related objects are updated during the program.
+@end itemize
- /* This call site is still checked. */
- (*foo2)();
+It's the programmer's responsibility to make sure the above requirements to
+be kept all the time. Otherwise the compiler reports warnings and
+the results of the array bound sanitizer and the
+@code{__builtin_dynamic_object_size} built-in are undefined.
- return 0;
-@}
+One important feature of the attribute is that a reference to the flexible
+array member field uses the latest value assigned to the field that
+represents the number of the elements before that reference. For example,
+
+@smallexample
+ p->count = val1;
+ p->array[20] = 0; // ref1 to p->array
+ p->count = val2;
+ p->array[30] = 0; // ref2 to p->array
@end smallexample
-@cindex @code{cf_check} function attribute, x86
-@item cf_check
+@noindent
+In the above, @code{ref1} uses @code{val1} as the number of the elements in
+@code{p->array}, and @code{ref2} uses @code{val2} as the number of elements
+in @code{p->array}.
-The @code{cf_check} attribute on a function is used to inform the
-compiler that ENDBR instruction should be placed at the function
-entry when @option{-fcf-protection=branch} is enabled.
+@cindex @code{alloc_size} variable attribute
+@item alloc_size (@var{position})
+@itemx alloc_size (@var{position-1}, @var{position-2})
+The @code{alloc_size} variable attribute may be applied to the declaration
+of a pointer to a function that returns a pointer and takes at least one
+argument of an integer type. It indicates that the returned pointer points
+to an object whose size is given by the function argument at @var{position},
+or by the product of the arguments at @var{position-1} and @var{position-2}.
+Meaningful sizes are positive values less than @code{PTRDIFF_MAX}. Other
+sizes are diagnosed when detected. GCC uses this information to improve
+the results of @code{__builtin_object_size}.
-@cindex @code{indirect_return} function attribute, x86
-@item indirect_return
+For instance, the following declarations
-The @code{indirect_return} attribute can be applied to a function,
-as well as variable or type of function pointer to inform the
-compiler that the function may return via indirect branch.
+@smallexample
+typedef __attribute__ ((alloc_size (1, 2))) void*
+ (*calloc_ptr) (size_t, size_t);
+typedef __attribute__ ((alloc_size (1))) void*
+ (*malloc_ptr) (size_t);
+@end smallexample
-@cindex @code{fentry_name} function attribute, x86
-@item fentry_name("@var{name}")
-On x86 targets, the @code{fentry_name} attribute sets the function to
-call on function entry when function instrumentation is enabled
-with @option{-pg -mfentry}. When @var{name} is nop then a 5 byte
-nop sequence is generated.
+@noindent
+specify that @code{calloc_ptr} is a pointer of a function that, like
+the standard C function @code{calloc}, returns an object whose size
+is given by the product of arguments 1 and 2, and similarly, that
+@code{malloc_ptr}, like the standard C function @code{malloc},
+returns an object whose size is given by argument 1 to the function.
-@cindex @code{fentry_section} function attribute, x86
-@item fentry_section("@var{name}")
-On x86 targets, the @code{fentry_section} attribute sets the name
-of the section to record function entry instrumentation calls in when
-enabled with @option{-pg -mrecord-mcount}
+@cindex @code{cleanup} variable attribute
+@item cleanup (@var{cleanup_function})
+The @code{cleanup} attribute runs a function when the variable goes
+out of scope. This attribute can only be applied to auto function
+scope variables; it may not be applied to parameters or variables
+with static storage duration. The function must take one parameter,
+a pointer to a type compatible with the variable. The return value
+of the function (if any) is ignored.
-@cindex @code{nodirect_extern_access} function attribute
-@opindex mno-direct-extern-access
-@item nodirect_extern_access
-This attribute, attached to a global variable or function, is the
-counterpart to option @option{-mno-direct-extern-access}.
+When multiple variables in the same scope have @code{cleanup}
+attributes, at exit from the scope their associated cleanup functions
+are run in reverse order of definition (last defined, first
+cleanup).
-@end table
+If @option{-fexceptions} is enabled, then @var{cleanup_function}
+is run during the stack unwinding that happens during the
+processing of the exception. Note that the @code{cleanup} attribute
+does not allow the exception to be caught, only to perform an action.
+It is undefined what happens if @var{cleanup_function} does not
+return normally.
-@subsubsection 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
-a function declared with @code{target("sse3")} can inline a function
-with @code{target("sse2")}, since @code{-msse3} implies @code{-msse2}.
+@cindex @code{common} variable attribute
+@cindex @code{nocommon} variable attribute
+@opindex fcommon
+@opindex fno-common
+@item common
+@itemx nocommon
+The @code{common} attribute requests GCC to place a variable in
+``common'' storage. The @code{nocommon} attribute requests the
+opposite---to allocate space for it directly.
-Besides the basic rule, when a function specifies
-@code{target("arch=@var{ARCH}")} or @code{target("tune=@var{TUNE}")}
-attribute, the inlining rule will be different. It allows inlining of
-a function with default @option{-march=x86-64} and
-@option{-mtune=generic} specified, or a function that has a subset
-of ISA features and marked with always_inline.
+These attributes override the default chosen by the
+@option{-fno-common} and @option{-fcommon} flags respectively.
-@node Xstormy16 Function Attributes
-@subsection Xstormy16 Function Attributes
+@cindex @code{copy} variable attribute
+@item copy
+@itemx copy (@var{variable})
+The @code{copy} attribute applies the set of attributes with which
+@var{variable} has been declared to the declaration of the variable
+to which the attribute is applied. The attribute is designed for
+libraries that define aliases that are expected to specify the same
+set of attributes as the aliased symbols. The @code{copy} attribute
+can be used with variables, functions or types. However, the kind
+of symbol to which the attribute is applied (either varible or
+function) must match the kind of symbol to which the argument refers.
+The @code{copy} attribute copies only syntactic and semantic attributes
+but not attributes that affect a symbol's linkage or visibility such as
+@code{alias}, @code{visibility}, or @code{weak}. The @code{deprecated}
+attribute is also not copied. @xref{Common Function Attributes}.
+@xref{Common Type Attributes}.
-These function attributes are supported by the Xstormy16 back end:
+@cindex @code{deprecated} variable attribute
+@item deprecated
+@itemx deprecated (@var{msg})
+The @code{deprecated} attribute results in a warning if the variable
+is used anywhere in the source file. This is useful when identifying
+variables that are expected to be removed in a future version of a
+program. The warning also includes the location of the declaration
+of the deprecated variable, to enable users to easily find further
+information about why the variable is deprecated, or what they should
+do instead. Note that the warning only occurs for uses:
-@table @code
-@cindex @code{interrupt} function attribute, Xstormy16
-@item interrupt
-Use this attribute to indicate
-that the specified function is an interrupt handler. The compiler generates
-function entry and exit sequences suitable for use in an interrupt handler
-when this attribute is present.
-@end table
+@smallexample
+extern int old_var __attribute__ ((deprecated));
+extern int old_var;
+int new_fn () @{ return old_var; @}
+@end smallexample
-@node Variable Attributes
-@section Specifying Attributes of Variables
-@cindex attribute of variables
-@cindex variable attributes
+@noindent
+results in a warning on line 3 but not line 2. The optional @var{msg}
+argument, which must be a string, is printed in the warning if
+present.
-You can use attributes to specify special properties
-of variables, function parameters, or structure, union, and, in C++, class
-members. Some attributes are currently
-defined generically for variables. Other attributes are defined for
-variables on particular target systems. Other attributes are available
-for functions (@pxref{Function Attributes}), labels (@pxref{Label Attributes}),
-enumerators (@pxref{Enumerator Attributes}), statements
-(@pxref{Statement Attributes}), and for types (@pxref{Type Attributes}).
-Other front ends might define more attributes
-(@pxref{C++ Extensions,,Extensions to the C++ Language}).
+The @code{deprecated} attribute can also be used for functions and
+types (@pxref{Common Function Attributes},
+@pxref{Common Type Attributes}).
-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::} prefix on attribute names. Note that the exact rules for
-placement of attributes in your source code are different depending on
-which syntax you use. @xref{Attribute Syntax}, for details.
+The message attached to the attribute is affected by the setting of
+the @option{-fmessage-length} option.
-@menu
-* Common Variable Attributes::
-* ARC Variable Attributes::
-* AVR Variable Attributes::
-* Blackfin Variable Attributes::
-* H8/300 Variable Attributes::
-* IA-64 Variable Attributes::
-* LoongArch Variable Attributes::
-* M32R/D Variable Attributes::
-* Microsoft Windows Variable Attributes::
-* MSP430 Variable Attributes::
-* Nvidia PTX Variable Attributes::
-* PowerPC Variable Attributes::
-* RL78 Variable Attributes::
-* V850 Variable Attributes::
-* x86 Variable Attributes::
-* Xstormy16 Variable Attributes::
-@end menu
+@cindex @code{mode} variable attribute
+@item mode (@var{mode})
+This attribute specifies the data type for the declaration---whichever
+type corresponds to the mode @var{mode}. This in effect lets you
+request an integer or floating-point type according to its width.
-@node Common Variable Attributes
-@subsection Common Variable Attributes
+@xref{Machine Modes,,, gccint, GNU Compiler Collection (GCC) Internals},
+for a list of the possible keywords for @var{mode}.
+You may also specify a mode of @code{byte} or @code{__byte__} to
+indicate the mode corresponding to a one-byte integer, @code{word} or
+@code{__word__} for the mode of a one-word integer, and @code{pointer}
+or @code{__pointer__} for the mode used to represent pointers.
-The following attributes are supported on most targets.
+@cindex @code{no_icf} variable attribute
+@item no_icf
+This variable attribute prevents a variable from being merged with another
+equivalent variable.
-@table @code
-@c Keep this table alphabetized by attribute name. Treat _ as space.
+@cindex @code{noinit} variable attribute
+@item noinit
+Any data with the @code{noinit} attribute will not be initialized by
+the C runtime startup code, or the program loader. Not initializing
+data in this way can reduce program startup times.
-@cindex @code{alias} variable attribute
-@item alias ("@var{target}")
-The @code{alias} variable attribute causes the declaration to be emitted
-as an alias for another symbol known as an @dfn{alias target}. Except
-for top-level qualifiers the alias target must have the same type as
-the alias. For instance, the following
+This attribute is specific to ELF targets and relies on the linker
+script to place sections with the @code{.noinit} prefix in the right
+location.
+
+@cindex @code{nonstring} variable attribute
+@item nonstring
+The @code{nonstring} variable attribute specifies that an object or member
+declaration with type array of @code{char}, @code{signed char}, or
+@code{unsigned char}, or pointer to such a type is intended to store
+character arrays that do not necessarily contain a terminating @code{NUL}.
+This is useful in detecting uses of such arrays or pointers with functions
+that expect @code{NUL}-terminated strings, and to avoid warnings when such
+an array or pointer is used as an argument to a bounded string manipulation
+function such as @code{strncpy}. For example, without the attribute, GCC
+will issue a warning for the @code{strncpy} call below because it may
+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
+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
+provided a suitable bound is specified, and not diagnosed.
@smallexample
-int var_target;
-extern int __attribute__ ((alias ("var_target"))) var_alias;
-@end smallexample
+struct Data
+@{
+ char name [32] __attribute__ ((nonstring));
+@};
-@noindent
-defines @code{var_alias} to be an alias for the @code{var_target} variable.
+int f (struct Data *pd, const char *s)
+@{
+ strncpy (pd->name, s, sizeof pd->name);
+ @dots{}
+ return strlen (pd->name); // unsafe, gets a warning
+@}
+@end smallexample
-It is an error if the alias target is not defined in the same translation
-unit as the alias.
+@cindex @code{objc_nullability} variable attribute
+@item objc_nullability (@var{nullability kind}) @r{(Objective-C and Objective-C++ only)}
+This attribute applies to pointer variables only. It allows marking the
+pointer with one of four possible values describing the conditions under
+which the pointer might have a @code{nil} value. In most cases, the
+attribute is intended to be an internal representation for property and
+method nullability (specified by language keywords); it is not recommended
+to use it directly.
-Note that in the absence of the attribute GCC assumes that distinct
-declarations with external linkage denote distinct objects. Using both
-the alias and the alias target to access the same object is undefined
-in a translation unit without a declaration of the alias with the attribute.
+When @var{nullability kind} is @code{"unspecified"} or @code{0}, nothing is
+known about the conditions in which the pointer might be @code{nil}. Making
+this state specific serves to avoid false positives in diagnostics.
-This attribute requires assembler and object file support, and may not be
-available on all targets.
+When @var{nullability kind} is @code{"nonnull"} or @code{1}, the pointer has
+no meaning if it is @code{nil} and thus the compiler is free to emit
+diagnostics if it can be determined that the value will be @code{nil}.
-@cindex @code{aligned} variable attribute
-@item aligned
-@itemx aligned (@var{alignment})
-The @code{aligned} attribute specifies a minimum alignment for the variable
-or structure field, measured in bytes. When specified, @var{alignment} must
-be an integer constant power of 2. Specifying no @var{alignment} argument
-implies the maximum alignment for the target, which is often, but by no
-means always, 8 or 16 bytes.
-
-For example, the declaration:
+When @var{nullability kind} is @code{"nullable"} or @code{2}, the pointer might
+be @code{nil} and carry meaning as such.
-@smallexample
-int x __attribute__ ((aligned (16))) = 0;
-@end smallexample
+When @var{nullability kind} is @code{"resettable"} or @code{3} (used only in
+the context of property attribute lists) this describes the case in which a
+property setter may take the value @code{nil} (which perhaps causes the
+property to be reset in some manner to a default) but for which the property
+getter will never validly return @code{nil}.
-@noindent
-causes the compiler to allocate the global variable @code{x} on a
-16-byte boundary. On a 68040, this could be used in conjunction with
-an @code{asm} expression to access the @code{move16} instruction which
-requires 16-byte aligned operands.
+@cindex @code{packed} variable attribute
+@item packed
+The @code{packed} attribute specifies that a structure member should have
+the smallest possible alignment---one bit for a bit-field and one byte
+otherwise, unless a larger value is specified with the @code{aligned}
+attribute. The attribute does not apply to non-member objects.
-You can also specify the alignment of structure fields. For example, to
-create a double-word aligned @code{int} pair, you could write:
+For example in the structure below, the member array @code{x} is packed
+so that it immediately follows @code{a} with no intervening padding:
@smallexample
-struct foo @{ int x[2] __attribute__ ((aligned (8))); @};
+struct foo
+@{
+ char a;
+ int x[2] __attribute__ ((packed));
+@};
@end smallexample
-@noindent
-This is an alternative to creating a union with a @code{double} member,
-which forces the union to be double-word aligned.
-
-As in the preceding examples, you can explicitly specify the alignment
-(in bytes) that you wish the compiler to use for a given variable or
-structure field. Alternatively, you can leave out the alignment factor
-and just ask the compiler to align a variable or field to the
-default alignment for the target architecture you are compiling for.
-The default alignment is sufficient for all scalar types, but may not be
-enough for all vector types on a target that supports vector operations.
-The default alignment is fixed for a particular target ABI.
+@emph{Note:} The 4.1, 4.2 and 4.3 series of GCC ignore the
+@code{packed} attribute on bit-fields of type @code{char}. This has
+been fixed in GCC 4.4 but the change can lead to differences in the
+structure layout. See the documentation of
+@option{-Wpacked-bitfield-compat} for more information.
-GCC also provides a target specific macro @code{__BIGGEST_ALIGNMENT__},
-which is the largest alignment ever used for any data type on the
-target machine you are compiling for. For example, you could write:
+@cindex @code{persistent} variable attribute
+@item persistent
+Any data with the @code{persistent} attribute will not be initialized by
+the C runtime startup code, but will be initialized by the program
+loader. This enables the value of the variable to @samp{persist}
+between processor resets.
-@smallexample
-short array[3] __attribute__ ((aligned (__BIGGEST_ALIGNMENT__)));
-@end smallexample
+This attribute is specific to ELF targets and relies on the linker
+script to place the sections with the @code{.persistent} prefix in the
+right location. Specifically, some type of non-volatile, writable
+memory is required.
-The compiler automatically sets the alignment for the declared
-variable or field to @code{__BIGGEST_ALIGNMENT__}. Doing this can
-often make copy operations more efficient, because the compiler can
-use whatever instructions copy the biggest chunks of memory when
-performing copies to or from the variables or fields that you have
-aligned this way. Note that the value of @code{__BIGGEST_ALIGNMENT__}
-may change depending on command-line options.
+@cindex @code{section} variable attribute
+@item section ("@var{section-name}")
+Normally, the compiler places the objects it generates in sections like
+@code{data} and @code{bss}. Sometimes, however, you need additional sections,
+or you need certain particular variables to appear in special sections,
+for example to map to special hardware. The @code{section}
+attribute specifies that a variable (or function) lives in a particular
+section. For example, this small program uses several specific section names:
-When used on a struct, or struct member, the @code{aligned} attribute can
-only increase the alignment; in order to decrease it, the @code{packed}
-attribute must be specified as well. When used as part of a typedef, the
-@code{aligned} attribute can both increase and decrease alignment, and
-specifying the @code{packed} attribute generates a warning.
+@smallexample
+struct duart a __attribute__ ((section ("DUART_A"))) = @{ 0 @};
+struct duart b __attribute__ ((section ("DUART_B"))) = @{ 0 @};
+char stack[10000] __attribute__ ((section ("STACK"))) = @{ 0 @};
+int init_data __attribute__ ((section ("INITDATA")));
-Note that the effectiveness of @code{aligned} attributes for static
-variables may be limited by inherent limitations in the system linker
-and/or object file format. On some systems, the linker is
-only able to arrange for variables to be aligned up to a certain maximum
-alignment. (For some linkers, the maximum supported alignment may
-be very very small.) If your linker is only able to align variables
-up to a maximum of 8-byte alignment, then specifying @code{aligned(16)}
-in an @code{__attribute__} still only provides you with 8-byte
-alignment. See your linker documentation for further information.
+main()
+@{
+ /* @r{Initialize stack pointer} */
+ init_sp (stack + sizeof (stack));
-Stack variables are not affected by linker restrictions; GCC can properly
-align them on any target.
+ /* @r{Initialize initialized data} */
+ memcpy (&init_data, &data, &edata - &data);
-The @code{aligned} attribute can also be used for functions
-(@pxref{Common Function Attributes}.)
+ /* @r{Turn on the serial ports} */
+ init_duart (&a);
+ init_duart (&b);
+@}
+@end smallexample
-@cindex @code{counted_by} variable attribute
-@item counted_by (@var{count})
-The @code{counted_by} attribute may be attached to the C99 flexible array
-member of a structure. It indicates that the number of the elements of the
-array is given by the field "@var{count}" in the same structure as the
-flexible array member.
+@noindent
+Use the @code{section} attribute with
+@emph{global} variables and not @emph{local} variables,
+as shown in the example.
-This attribute is available only in C for now.
-In C++ this attribute is ignored.
+You may use the @code{section} attribute with initialized or
+uninitialized global variables but the linker requires
+each object be defined once, with the exception that uninitialized
+variables tentatively go in the @code{common} (or @code{bss}) section
+and can be multiply ``defined''. Using the @code{section} attribute
+changes what section the variable goes into and may cause the
+linker to issue an error if an uninitialized variable has multiple
+definitions. You can force a variable to be initialized with the
+@option{-fno-common} flag or the @code{nocommon} attribute.
-GCC may use this information to improve detection of object size information
-for such structures and provide better results in compile-time diagnostics
-and runtime features like the array bound sanitizer and
-the @code{__builtin_dynamic_object_size}.
+Some file formats do not support arbitrary sections so the @code{section}
+attribute is not available on all platforms.
+If you need to map the entire contents of a module to a particular
+section, consider using the facilities of the linker instead.
-For instance, the following code:
+@cindex @code{strict_flex_array} variable attribute
+@item strict_flex_array (@var{level})
+The @code{strict_flex_array} attribute should be attached to the trailing
+array field of a structure. It controls when to treat the trailing array
+field of a structure as a flexible array member for the purposes of accessing
+the elements of such an array.
+@var{level} must be an integer between 0 to 3.
-@smallexample
-struct P @{
- size_t count;
- char other;
- char array[] __attribute__ ((counted_by (count)));
-@} *p;
-@end smallexample
+@var{level}=0 is the least strict level, all trailing arrays of structures
+are treated as flexible array members. @var{level}=3 is the strictest level,
+only when the trailing array is declared as a flexible array member per C99
+standard onwards (@samp{[]}), it is treated as a flexible array member.
-@noindent
-specifies that the @code{array} is a flexible array member whose number of
-elements is given by the field @code{count} in the same structure.
+There are two more levels in between 0 and 3, which are provided to
+support older code that uses the GCC zero-length array extension
+(@samp{[0]}) or one-element array as flexible array members
+(@samp{[1]}). When @var{level} is 1, the trailing array is treated as
+a flexible array member when it is declared as either @samp{[]},
+@samp{[0]}, or @samp{[1]}. When @var{level} is 2, the trailing array
+is treated as a flexible array member when it is declared as either
+@samp{[]}, or @samp{[0]}.
-The field that represents the number of the elements should have an
-integer type. Otherwise, the compiler reports an error and ignores
+This attribute can be used with or without the
+@option{-fstrict-flex-arrays} command-line option. When both the
+attribute and the option are present at the same time, the level of
+the strictness for the specific trailing array field is determined by
the attribute.
-When the field that represents the number of the elements is assigned a
-negative integer value, the compiler treats the value as zero.
+The @code{strict_flex_array} attribute interacts with the
+@option{-Wstrict-flex-arrays} option. @xref{Warning Options}, for more
+information.
-An explicit @code{counted_by} annotation defines a relationship between
-two objects, @code{p->array} and @code{p->count}, and there are the
-following requirements on the relationship between this pair:
+@cindex @code{tls_model} variable attribute
+@item tls_model ("@var{tls_model}")
+The @code{tls_model} attribute sets thread-local storage model
+(@pxref{Thread-Local}) of a particular @code{__thread} variable,
+overriding @option{-ftls-model=} command-line switch on a per-variable
+basis.
+The @var{tls_model} argument should be one of @code{global-dynamic},
+@code{local-dynamic}, @code{initial-exec} or @code{local-exec}.
-@itemize @bullet
-@item
-@code{p->count} must be initialized before the first reference to
-@code{p->array};
+Not all targets support this attribute.
-@item
-@code{p->array} has @emph{at least} @code{p->count} number of elements
-available all the time. This relationship must hold even after any of
-these related objects are updated during the program.
-@end itemize
+@cindex @code{unavailable} variable attribute
+@item unavailable
+@itemx unavailable (@var{msg})
+The @code{unavailable} attribute indicates that the variable so marked
+is not available, if it is used anywhere in the source file. It behaves
+in the same manner as the @code{deprecated} attribute except that the
+compiler will emit an error rather than a warning.
-It's the programmer's responsibility to make sure the above requirements to
-be kept all the time. Otherwise the compiler reports warnings and
-the results of the array bound sanitizer and the
-@code{__builtin_dynamic_object_size} built-in are undefined.
+It is expected that items marked as @code{deprecated} will eventually be
+withdrawn from interfaces, and then become unavailable. This attribute
+allows for marking them appropriately.
-One important feature of the attribute is that a reference to the flexible
-array member field uses the latest value assigned to the field that
-represents the number of the elements before that reference. For example,
+The @code{unavailable} attribute can also be used for functions and
+types (@pxref{Common Function Attributes},
+@pxref{Common Type Attributes}).
-@smallexample
- p->count = val1;
- p->array[20] = 0; // ref1 to p->array
- p->count = val2;
- p->array[30] = 0; // ref2 to p->array
-@end smallexample
+@cindex @code{unused} variable attribute
+@item unused
+This attribute, attached to a variable or structure field, means that
+the variable or field is meant to be possibly unused. GCC does not
+produce a warning for this variable or field.
-@noindent
-In the above, @code{ref1} uses @code{val1} as the number of the elements in
-@code{p->array}, and @code{ref2} uses @code{val2} as the number of elements
-in @code{p->array}.
+@cindex @code{used} variable attribute
+@item used
+This attribute, attached to a variable with static storage, means that
+the variable must be emitted even if it appears that the variable is not
+referenced.
-@cindex @code{alloc_size} variable attribute
-@item alloc_size (@var{position})
-@itemx alloc_size (@var{position-1}, @var{position-2})
-The @code{alloc_size} variable attribute may be applied to the declaration
-of a pointer to a function that returns a pointer and takes at least one
-argument of an integer type. It indicates that the returned pointer points
-to an object whose size is given by the function argument at @var{position},
-or by the product of the arguments at @var{position-1} and @var{position-2}.
-Meaningful sizes are positive values less than @code{PTRDIFF_MAX}. Other
-sizes are diagnosed when detected. GCC uses this information to improve
-the results of @code{__builtin_object_size}.
-
-For instance, the following declarations
-
-@smallexample
-typedef __attribute__ ((alloc_size (1, 2))) void*
- (*calloc_ptr) (size_t, size_t);
-typedef __attribute__ ((alloc_size (1))) void*
- (*malloc_ptr) (size_t);
-@end smallexample
-
-@noindent
-specify that @code{calloc_ptr} is a pointer of a function that, like
-the standard C function @code{calloc}, returns an object whose size
-is given by the product of arguments 1 and 2, and similarly, that
-@code{malloc_ptr}, like the standard C function @code{malloc},
-returns an object whose size is given by argument 1 to the function.
-
-@cindex @code{cleanup} variable attribute
-@item cleanup (@var{cleanup_function})
-The @code{cleanup} attribute runs a function when the variable goes
-out of scope. This attribute can only be applied to auto function
-scope variables; it may not be applied to parameters or variables
-with static storage duration. The function must take one parameter,
-a pointer to a type compatible with the variable. The return value
-of the function (if any) is ignored.
+When applied to a static data member of a C++ class template, the
+attribute also means that the member is instantiated if the
+class itself is instantiated.
-When multiple variables in the same scope have @code{cleanup}
-attributes, at exit from the scope their associated cleanup functions
-are run in reverse order of definition (last defined, first
-cleanup).
+@cindex @code{retain} variable attribute
+@item retain
+For ELF targets that support the GNU or FreeBSD OSABIs, this attribute
+will save the variable from linker garbage collection. To support
+this behavior, variables that have not been placed in specific sections
+(e.g. by the @code{section} attribute, or the @code{-fdata-sections} option),
+will be placed in new, unique sections.
-If @option{-fexceptions} is enabled, then @var{cleanup_function}
-is run during the stack unwinding that happens during the
-processing of the exception. Note that the @code{cleanup} attribute
-does not allow the exception to be caught, only to perform an action.
-It is undefined what happens if @var{cleanup_function} does not
-return normally.
+This additional functionality requires Binutils version 2.36 or later.
-@cindex @code{common} variable attribute
-@cindex @code{nocommon} variable attribute
-@opindex fcommon
-@opindex fno-common
-@item common
-@itemx nocommon
-The @code{common} attribute requests GCC to place a variable in
-``common'' storage. The @code{nocommon} attribute requests the
-opposite---to allocate space for it directly.
+@cindex @code{uninitialized} variable attribute
+@item uninitialized
+This attribute, attached to a variable with automatic storage, means that
+the variable should not be automatically initialized by the compiler when
+the option @code{-ftrivial-auto-var-init} presents.
-These attributes override the default chosen by the
-@option{-fno-common} and @option{-fcommon} flags respectively.
+With the option @code{-ftrivial-auto-var-init}, all the automatic variables
+that do not have explicit initializers will be initialized by the compiler.
+These additional compiler initializations might incur run-time overhead,
+sometimes dramatically. This attribute can be used to mark some variables
+to be excluded from such automatic initialization in order to reduce runtime
+overhead.
-@cindex @code{copy} variable attribute
-@item copy
-@itemx copy (@var{variable})
-The @code{copy} attribute applies the set of attributes with which
-@var{variable} has been declared to the declaration of the variable
-to which the attribute is applied. The attribute is designed for
-libraries that define aliases that are expected to specify the same
-set of attributes as the aliased symbols. The @code{copy} attribute
-can be used with variables, functions or types. However, the kind
-of symbol to which the attribute is applied (either varible or
-function) must match the kind of symbol to which the argument refers.
-The @code{copy} attribute copies only syntactic and semantic attributes
-but not attributes that affect a symbol's linkage or visibility such as
-@code{alias}, @code{visibility}, or @code{weak}. The @code{deprecated}
-attribute is also not copied. @xref{Common Function Attributes}.
-@xref{Common Type Attributes}.
+This attribute has no effect when the option @code{-ftrivial-auto-var-init}
+is not present.
-@cindex @code{deprecated} variable attribute
-@item deprecated
-@itemx deprecated (@var{msg})
-The @code{deprecated} attribute results in a warning if the variable
-is used anywhere in the source file. This is useful when identifying
-variables that are expected to be removed in a future version of a
-program. The warning also includes the location of the declaration
-of the deprecated variable, to enable users to easily find further
-information about why the variable is deprecated, or what they should
-do instead. Note that the warning only occurs for uses:
+@cindex @code{vector_size} variable attribute
+@item vector_size (@var{bytes})
+This attribute specifies the vector size for the type of the declared
+variable, measured in bytes. The type to which it applies is known as
+the @dfn{base type}. The @var{bytes} argument must be a positive
+power-of-two multiple of the base type size. For example, the declaration:
@smallexample
-extern int old_var __attribute__ ((deprecated));
-extern int old_var;
-int new_fn () @{ return old_var; @}
+int foo __attribute__ ((vector_size (16)));
@end smallexample
@noindent
-results in a warning on line 3 but not line 2. The optional @var{msg}
-argument, which must be a string, is printed in the warning if
-present.
-
-The @code{deprecated} attribute can also be used for functions and
-types (@pxref{Common Function Attributes},
-@pxref{Common Type Attributes}).
-
-The message attached to the attribute is affected by the setting of
-the @option{-fmessage-length} option.
+causes the compiler to set the mode for @code{foo}, to be 16 bytes,
+divided into @code{int} sized units. Assuming a 32-bit @code{int},
+@code{foo}'s type is a vector of four units of four bytes each, and
+the corresponding mode of @code{foo} is @code{V4SI}.
+@xref{Vector Extensions}, for details of manipulating vector variables.
-@cindex @code{mode} variable attribute
-@item mode (@var{mode})
-This attribute specifies the data type for the declaration---whichever
-type corresponds to the mode @var{mode}. This in effect lets you
-request an integer or floating-point type according to its width.
+This attribute is only applicable to integral and floating scalars,
+although arrays, pointers, and function return values are allowed in
+conjunction with this construct.
-@xref{Machine Modes,,, gccint, GNU Compiler Collection (GCC) Internals},
-for a list of the possible keywords for @var{mode}.
-You may also specify a mode of @code{byte} or @code{__byte__} to
-indicate the mode corresponding to a one-byte integer, @code{word} or
-@code{__word__} for the mode of a one-word integer, and @code{pointer}
-or @code{__pointer__} for the mode used to represent pointers.
+Aggregates with this attribute are invalid, even if they are of the same
+size as a corresponding scalar. For example, the declaration:
-@cindex @code{no_icf} variable attribute
-@item no_icf
-This variable attribute prevents a variable from being merged with another
-equivalent variable.
+@smallexample
+struct S @{ int a; @};
+struct S __attribute__ ((vector_size (16))) foo;
+@end smallexample
-@cindex @code{noinit} variable attribute
-@item noinit
-Any data with the @code{noinit} attribute will not be initialized by
-the C runtime startup code, or the program loader. Not initializing
-data in this way can reduce program startup times.
+@noindent
+is invalid even if the size of the structure is the same as the size of
+the @code{int}.
-This attribute is specific to ELF targets and relies on the linker
-script to place sections with the @code{.noinit} prefix in the right
-location.
+@cindex @code{visibility} variable attribute
+@item visibility ("@var{visibility_type}")
+This attribute affects the linkage of the declaration to which it is attached.
+The @code{visibility} attribute is described in
+@ref{Common Function Attributes}.
-@cindex @code{nonstring} variable attribute
-@item nonstring
-The @code{nonstring} variable attribute specifies that an object or member
-declaration with type array of @code{char}, @code{signed char}, or
-@code{unsigned char}, or pointer to such a type is intended to store
-character arrays that do not necessarily contain a terminating @code{NUL}.
-This is useful in detecting uses of such arrays or pointers with functions
-that expect @code{NUL}-terminated strings, and to avoid warnings when such
-an array or pointer is used as an argument to a bounded string manipulation
-function such as @code{strncpy}. For example, without the attribute, GCC
-will issue a warning for the @code{strncpy} call below because it may
-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
-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
-provided a suitable bound is specified, and not diagnosed.
+@cindex @code{warn_if_not_aligned} variable attribute
+@item warn_if_not_aligned (@var{alignment})
+This attribute specifies a threshold for the structure field, measured
+in bytes. If the structure field is aligned below the threshold, a
+warning will be issued. For example, the declaration:
@smallexample
-struct Data
+struct foo
@{
- char name [32] __attribute__ ((nonstring));
+ int i1;
+ int i2;
+ unsigned long long x __attribute__ ((warn_if_not_aligned (16)));
@};
-
-int f (struct Data *pd, const char *s)
-@{
- strncpy (pd->name, s, sizeof pd->name);
- @dots{}
- return strlen (pd->name); // unsafe, gets a warning
-@}
@end smallexample
-@cindex @code{objc_nullability} variable attribute
-@item objc_nullability (@var{nullability kind}) @r{(Objective-C and Objective-C++ only)}
-This attribute applies to pointer variables only. It allows marking the
-pointer with one of four possible values describing the conditions under
-which the pointer might have a @code{nil} value. In most cases, the
-attribute is intended to be an internal representation for property and
-method nullability (specified by language keywords); it is not recommended
-to use it directly.
-
-When @var{nullability kind} is @code{"unspecified"} or @code{0}, nothing is
-known about the conditions in which the pointer might be @code{nil}. Making
-this state specific serves to avoid false positives in diagnostics.
-
-When @var{nullability kind} is @code{"nonnull"} or @code{1}, the pointer has
-no meaning if it is @code{nil} and thus the compiler is free to emit
-diagnostics if it can be determined that the value will be @code{nil}.
-
-When @var{nullability kind} is @code{"nullable"} or @code{2}, the pointer might
-be @code{nil} and carry meaning as such.
-
-When @var{nullability kind} is @code{"resettable"} or @code{3} (used only in
-the context of property attribute lists) this describes the case in which a
-property setter may take the value @code{nil} (which perhaps causes the
-property to be reset in some manner to a default) but for which the property
-getter will never validly return @code{nil}.
-
-@cindex @code{packed} variable attribute
-@item packed
-The @code{packed} attribute specifies that a structure member should have
-the smallest possible alignment---one bit for a bit-field and one byte
-otherwise, unless a larger value is specified with the @code{aligned}
-attribute. The attribute does not apply to non-member objects.
-
-For example in the structure below, the member array @code{x} is packed
-so that it immediately follows @code{a} with no intervening padding:
+@noindent
+causes the compiler to issue an warning on @code{struct foo}, like
+@samp{warning: alignment 8 of 'struct foo' is less than 16}.
+The compiler also issues a warning, like @samp{warning: 'x' offset
+8 in 'struct foo' isn't aligned to 16}, when the structure field has
+the misaligned offset:
@smallexample
-struct foo
+struct __attribute__ ((aligned (16))) foo
@{
- char a;
- int x[2] __attribute__ ((packed));
-@};
-@end smallexample
-
-@emph{Note:} The 4.1, 4.2 and 4.3 series of GCC ignore the
-@code{packed} attribute on bit-fields of type @code{char}. This has
-been fixed in GCC 4.4 but the change can lead to differences in the
-structure layout. See the documentation of
-@option{-Wpacked-bitfield-compat} for more information.
-
-@cindex @code{persistent} variable attribute
-@item persistent
-Any data with the @code{persistent} attribute will not be initialized by
-the C runtime startup code, but will be initialized by the program
-loader. This enables the value of the variable to @samp{persist}
-between processor resets.
-
-This attribute is specific to ELF targets and relies on the linker
-script to place the sections with the @code{.persistent} prefix in the
-right location. Specifically, some type of non-volatile, writable
-memory is required.
-
-@cindex @code{section} variable attribute
-@item section ("@var{section-name}")
-Normally, the compiler places the objects it generates in sections like
-@code{data} and @code{bss}. Sometimes, however, you need additional sections,
-or you need certain particular variables to appear in special sections,
-for example to map to special hardware. The @code{section}
-attribute specifies that a variable (or function) lives in a particular
-section. For example, this small program uses several specific section names:
-
-@smallexample
-struct duart a __attribute__ ((section ("DUART_A"))) = @{ 0 @};
-struct duart b __attribute__ ((section ("DUART_B"))) = @{ 0 @};
-char stack[10000] __attribute__ ((section ("STACK"))) = @{ 0 @};
-int init_data __attribute__ ((section ("INITDATA")));
-
-main()
-@{
- /* @r{Initialize stack pointer} */
- init_sp (stack + sizeof (stack));
-
- /* @r{Initialize initialized data} */
- memcpy (&init_data, &data, &edata - &data);
-
- /* @r{Turn on the serial ports} */
- init_duart (&a);
- init_duart (&b);
-@}
-@end smallexample
-
-@noindent
-Use the @code{section} attribute with
-@emph{global} variables and not @emph{local} variables,
-as shown in the example.
-
-You may use the @code{section} attribute with initialized or
-uninitialized global variables but the linker requires
-each object be defined once, with the exception that uninitialized
-variables tentatively go in the @code{common} (or @code{bss}) section
-and can be multiply ``defined''. Using the @code{section} attribute
-changes what section the variable goes into and may cause the
-linker to issue an error if an uninitialized variable has multiple
-definitions. You can force a variable to be initialized with the
-@option{-fno-common} flag or the @code{nocommon} attribute.
-
-Some file formats do not support arbitrary sections so the @code{section}
-attribute is not available on all platforms.
-If you need to map the entire contents of a module to a particular
-section, consider using the facilities of the linker instead.
-
-@cindex @code{strict_flex_array} variable attribute
-@item strict_flex_array (@var{level})
-The @code{strict_flex_array} attribute should be attached to the trailing
-array field of a structure. It controls when to treat the trailing array
-field of a structure as a flexible array member for the purposes of accessing
-the elements of such an array.
-@var{level} must be an integer between 0 to 3.
-
-@var{level}=0 is the least strict level, all trailing arrays of structures
-are treated as flexible array members. @var{level}=3 is the strictest level,
-only when the trailing array is declared as a flexible array member per C99
-standard onwards (@samp{[]}), it is treated as a flexible array member.
-
-There are two more levels in between 0 and 3, which are provided to
-support older code that uses the GCC zero-length array extension
-(@samp{[0]}) or one-element array as flexible array members
-(@samp{[1]}). When @var{level} is 1, the trailing array is treated as
-a flexible array member when it is declared as either @samp{[]},
-@samp{[0]}, or @samp{[1]}. When @var{level} is 2, the trailing array
-is treated as a flexible array member when it is declared as either
-@samp{[]}, or @samp{[0]}.
-
-This attribute can be used with or without the
-@option{-fstrict-flex-arrays} command-line option. When both the
-attribute and the option are present at the same time, the level of
-the strictness for the specific trailing array field is determined by
-the attribute.
-
-The @code{strict_flex_array} attribute interacts with the
-@option{-Wstrict-flex-arrays} option. @xref{Warning Options}, for more
-information.
-
-@cindex @code{tls_model} variable attribute
-@item tls_model ("@var{tls_model}")
-The @code{tls_model} attribute sets thread-local storage model
-(@pxref{Thread-Local}) of a particular @code{__thread} variable,
-overriding @option{-ftls-model=} command-line switch on a per-variable
-basis.
-The @var{tls_model} argument should be one of @code{global-dynamic},
-@code{local-dynamic}, @code{initial-exec} or @code{local-exec}.
-
-Not all targets support this attribute.
-
-@cindex @code{unavailable} variable attribute
-@item unavailable
-@itemx unavailable (@var{msg})
-The @code{unavailable} attribute indicates that the variable so marked
-is not available, if it is used anywhere in the source file. It behaves
-in the same manner as the @code{deprecated} attribute except that the
-compiler will emit an error rather than a warning.
-
-It is expected that items marked as @code{deprecated} will eventually be
-withdrawn from interfaces, and then become unavailable. This attribute
-allows for marking them appropriately.
-
-The @code{unavailable} attribute can also be used for functions and
-types (@pxref{Common Function Attributes},
-@pxref{Common Type Attributes}).
-
-@cindex @code{unused} variable attribute
-@item unused
-This attribute, attached to a variable or structure field, means that
-the variable or field is meant to be possibly unused. GCC does not
-produce a warning for this variable or field.
-
-@cindex @code{used} variable attribute
-@item used
-This attribute, attached to a variable with static storage, means that
-the variable must be emitted even if it appears that the variable is not
-referenced.
-
-When applied to a static data member of a C++ class template, the
-attribute also means that the member is instantiated if the
-class itself is instantiated.
-
-@cindex @code{retain} variable attribute
-@item retain
-For ELF targets that support the GNU or FreeBSD OSABIs, this attribute
-will save the variable from linker garbage collection. To support
-this behavior, variables that have not been placed in specific sections
-(e.g. by the @code{section} attribute, or the @code{-fdata-sections} option),
-will be placed in new, unique sections.
-
-This additional functionality requires Binutils version 2.36 or later.
-
-@cindex @code{uninitialized} variable attribute
-@item uninitialized
-This attribute, attached to a variable with automatic storage, means that
-the variable should not be automatically initialized by the compiler when
-the option @code{-ftrivial-auto-var-init} presents.
-
-With the option @code{-ftrivial-auto-var-init}, all the automatic variables
-that do not have explicit initializers will be initialized by the compiler.
-These additional compiler initializations might incur run-time overhead,
-sometimes dramatically. This attribute can be used to mark some variables
-to be excluded from such automatic initialization in order to reduce runtime
-overhead.
-
-This attribute has no effect when the option @code{-ftrivial-auto-var-init}
-is not present.
-
-@cindex @code{vector_size} variable attribute
-@item vector_size (@var{bytes})
-This attribute specifies the vector size for the type of the declared
-variable, measured in bytes. The type to which it applies is known as
-the @dfn{base type}. The @var{bytes} argument must be a positive
-power-of-two multiple of the base type size. For example, the declaration:
-
-@smallexample
-int foo __attribute__ ((vector_size (16)));
-@end smallexample
-
-@noindent
-causes the compiler to set the mode for @code{foo}, to be 16 bytes,
-divided into @code{int} sized units. Assuming a 32-bit @code{int},
-@code{foo}'s type is a vector of four units of four bytes each, and
-the corresponding mode of @code{foo} is @code{V4SI}.
-@xref{Vector Extensions}, for details of manipulating vector variables.
-
-This attribute is only applicable to integral and floating scalars,
-although arrays, pointers, and function return values are allowed in
-conjunction with this construct.
-
-Aggregates with this attribute are invalid, even if they are of the same
-size as a corresponding scalar. For example, the declaration:
-
-@smallexample
-struct S @{ int a; @};
-struct S __attribute__ ((vector_size (16))) foo;
-@end smallexample
-
-@noindent
-is invalid even if the size of the structure is the same as the size of
-the @code{int}.
-
-@cindex @code{visibility} variable attribute
-@item visibility ("@var{visibility_type}")
-This attribute affects the linkage of the declaration to which it is attached.
-The @code{visibility} attribute is described in
-@ref{Common Function Attributes}.
-
-@cindex @code{warn_if_not_aligned} variable attribute
-@item warn_if_not_aligned (@var{alignment})
-This attribute specifies a threshold for the structure field, measured
-in bytes. If the structure field is aligned below the threshold, a
-warning will be issued. For example, the declaration:
-
-@smallexample
-struct foo
-@{
- int i1;
- int i2;
- unsigned long long x __attribute__ ((warn_if_not_aligned (16)));
-@};
-@end smallexample
-
-@noindent
-causes the compiler to issue an warning on @code{struct foo}, like
-@samp{warning: alignment 8 of 'struct foo' is less than 16}.
-The compiler also issues a warning, like @samp{warning: 'x' offset
-8 in 'struct foo' isn't aligned to 16}, when the structure field has
-the misaligned offset:
-
-@smallexample
-struct __attribute__ ((aligned (16))) foo
-@{
- int i1;
- int i2;
- unsigned long long x __attribute__ ((warn_if_not_aligned (16)));
+ int i1;
+ int i2;
+ unsigned long long x __attribute__ ((warn_if_not_aligned (16)));
@};
@end smallexample
that is not a pointer-to-function type, it is treated as applying
to the function type.
-@node Function Prototypes
-@section Prototypes and Old-Style Function Definitions
-@cindex function prototype declarations
-@cindex old-style function definitions
-@cindex promotion of formal parameters
-
-GNU C extends ISO C to allow a function prototype to override a later
-old-style non-prototype definition. Consider the following example:
-
-@smallexample
-/* @r{Use prototypes unless the compiler is old-fashioned.} */
-#ifdef __STDC__
-#define P(x) x
-#else
-#define P(x) ()
-#endif
-
-/* @r{Prototype function declaration.} */
-int isroot P((uid_t));
-
-/* @r{Old-style function definition.} */
-int
-isroot (x) /* @r{??? lossage here ???} */
- uid_t x;
-@{
- return x == 0;
-@}
-@end smallexample
-
-Suppose the type @code{uid_t} happens to be @code{short}. ISO C does
-not allow this example, because subword arguments in old-style
-non-prototype definitions are promoted. Therefore in this example the
-function definition's argument is really an @code{int}, which does not
-match the prototype argument type of @code{short}.
-
-This restriction of ISO C makes it hard to write code that is portable
-to traditional C compilers, because the programmer does not know
-whether the @code{uid_t} type is @code{short}, @code{int}, or
-@code{long}. Therefore, in cases like these GNU C allows a prototype
-to override a later old-style definition. More precisely, in GNU C, a
-function prototype argument type overrides the argument type specified
-by a later old-style definition if the former type is the same as the
-latter type before promotion. Thus in GNU C the above example is
-equivalent to the following:
-
-@smallexample
-int isroot (uid_t);
-
-int
-isroot (uid_t x)
-@{
- return x == 0;
-@}
-@end smallexample
-
-@noindent
-GNU C++ does not support old-style function definitions, so this
-extension is irrelevant.
-
-@node C++ Comments
-@section C++ Style Comments
-@cindex @code{//}
-@cindex C++ comments
-@cindex comments, C++ style
-
-In GNU C, you may use C++ style comments, which start with @samp{//} and
-continue until the end of the line. Many other C implementations allow
-such comments, and they are included in the 1999 C standard. However,
-C++ style comments are not recognized if you specify an @option{-std}
-option specifying a version of ISO C before C99, or @option{-ansi}
-(equivalent to @option{-std=c90}).
-
-@node Dollar Signs
-@section Dollar Signs in Identifier Names
-@cindex $
-@cindex dollar signs in identifier names
-@cindex identifier names, dollar signs in
-
-In GNU C, you may normally use dollar signs in identifier names.
-This is because many traditional C implementations allow such identifiers.
-However, dollar signs in identifiers are not supported on a few target
-machines, typically because the target assembler does not allow them.
-
-@node Character Escapes
-@section The Character @key{ESC} in Constants
-
-You can use the sequence @samp{\e} in a string or character constant to
-stand for the ASCII character @key{ESC}.
-
-@node Alignment
-@section Determining the Alignment of Functions, Types or Variables
-@cindex alignment
-@cindex type alignment
-@cindex variable alignment
-
-The keyword @code{__alignof__} determines the alignment requirement of
-a function, object, or a type, or the minimum alignment usually required
-by a type. Its syntax is just like @code{sizeof} and C11 @code{_Alignof}.
-
-For example, if the target machine requires a @code{double} value to be
-aligned on an 8-byte boundary, then @code{__alignof__ (double)} is 8.
-This is true on many RISC machines. On more traditional machine
-designs, @code{__alignof__ (double)} is 4 or even 2.
-
-Some machines never actually require alignment; they allow references to any
-data type even at an odd address. For these machines, @code{__alignof__}
-reports the smallest alignment that GCC gives the data type, usually as
-mandated by the target ABI.
-
-If the operand of @code{__alignof__} is an lvalue rather than a type,
-its value is the required alignment for its type, taking into account
-any minimum alignment specified by attribute @code{aligned}
-(@pxref{Common Variable Attributes}). For example, after this
-declaration:
-
-@smallexample
-struct foo @{ int x; char y; @} foo1;
-@end smallexample
-
-@noindent
-the value of @code{__alignof__ (foo1.y)} is 1, even though its actual
-alignment is probably 2 or 4, the same as @code{__alignof__ (int)}.
-It is an error to ask for the alignment of an incomplete type other
-than @code{void}.
-
-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 Inline
-@section An Inline Function is As Fast As a Macro
-@cindex inline functions
-@cindex integrating function code
-@cindex open coding
-@cindex macros, inline alternative
+@node Inline
+@section An Inline Function is As Fast As a Macro
+@cindex inline functions
+@cindex integrating function code
+@cindex open coding
+@cindex macros, inline alternative
By declaring a function inline, you can direct GCC to make
calls to that function faster. One way GCC can achieve this is to
to be inlined. If any uses of the function remain, they refer to
the single copy in the library.
-@node Const and Volatile Functions
-@section Const and Volatile Functions
-@cindex @code{const} applied to function
-@cindex @code{volatile} applied to function
-
-The C standard explicitly leaves the behavior of the @code{const} and
-@code{volatile} type qualifiers applied to functions undefined; these
-constructs can only arise through the use of @code{typedef}. As an extension,
-GCC defines this use of the @code{const} qualifier to have the same meaning
-as the GCC @code{const} function attribute, and the @code{volatile} qualifier
-to be equivalent to the @code{noreturn} attribute.
-@xref{Common Function Attributes}, for more information.
-
-As examples of this usage,
-
-@smallexample
-
-/* @r{Equivalent to:}
- void fatal () __attribute__ ((noreturn)); */
-typedef void voidfn ();
-volatile voidfn fatal;
-
-/* @r{Equivalent to:}
- extern int square (int) __attribute__ ((const)); */
-typedef int intfn (int);
-extern const intfn square;
-@end smallexample
-
-In general, using function attributes instead is preferred, since the
-attributes make both the intent of the code and its reliance on a GNU
-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 Volatiles
@section When is a Volatile Object Accessed?
@cindex accessing volatiles
explicitly clobbered, unless it is constrained to match an
output operand.
-@item
-For any input register that is implicitly popped by an @code{asm}, it is
-necessary to know how to adjust the stack to compensate for the pop.
-If any non-popped input is closer to the top of the reg-stack than
-the implicitly popped register, it would not be possible to know what the
-stack looked like---it's not clear how the rest of the stack ``slides
-up''.
+@item
+For any input register that is implicitly popped by an @code{asm}, it is
+necessary to know how to adjust the stack to compensate for the pop.
+If any non-popped input is closer to the top of the reg-stack than
+the implicitly popped register, it would not be possible to know what the
+stack looked like---it's not clear how the rest of the stack ``slides
+up''.
+
+All implicitly popped input registers must be closer to the top of
+the reg-stack than any input that is not implicitly popped.
+
+It is possible that if an input dies in an @code{asm}, the compiler might
+use the input register for an output reload. Consider this example:
+
+@smallexample
+asm ("foo" : "=t" (a) : "f" (b));
+@end smallexample
+
+@noindent
+This code says that input @code{b} is not popped by the @code{asm}, and that
+the @code{asm} pushes a result onto the reg-stack, i.e., the stack is one
+deeper after the @code{asm} than it was before. But, it is possible that
+reload may think that it can use the same register for both the input and
+the output.
+
+To prevent this from happening,
+if any input operand uses the @samp{f} constraint, all output register
+constraints must use the @samp{&} early-clobber modifier.
+
+The example above is correctly written as:
+
+@smallexample
+asm ("foo" : "=&t" (a) : "f" (b));
+@end smallexample
+
+@item
+Some operands need to be in particular places on the stack. All
+output operands fall in this category---GCC has no other way to
+know which registers the outputs appear in unless you indicate
+this in the constraints.
+
+Output operands must specifically indicate which register an output
+appears in after an @code{asm}. @samp{=f} is not allowed: the operand
+constraints must select a class with a single register.
+
+@item
+Output operands may not be ``inserted'' between existing stack registers.
+Since no 387 opcode uses a read/write operand, all output operands
+are dead before the @code{asm}, and are pushed by the @code{asm}.
+It makes no sense to push anywhere but the top of the reg-stack.
+
+Output operands must start at the top of the reg-stack: output
+operands may not ``skip'' a register.
+
+@item
+Some @code{asm} statements may need extra stack space for internal
+calculations. This can be guaranteed by clobbering stack registers
+unrelated to the inputs and outputs.
+
+@end enumerate
+
+This @code{asm}
+takes one input, which is internally popped, and produces two outputs.
+
+@smallexample
+asm ("fsincos" : "=t" (cos), "=u" (sin) : "0" (inp));
+@end smallexample
+
+@noindent
+This @code{asm} takes two inputs, which are popped by the @code{fyl2xp1} opcode,
+and replaces them with one output. The @code{st(1)} clobber is necessary
+for the compiler to know that @code{fyl2xp1} pops both inputs.
+
+@smallexample
+asm ("fyl2xp1" : "=t" (result) : "0" (x), "u" (y) : "st(1)");
+@end smallexample
+
+@anchor{msp430Operandmodifiers}
+@subsubsection MSP430 Operand Modifiers
+
+The list below describes the supported modifiers and their effects for MSP430.
+
+@multitable @columnfractions .10 .90
+@headitem Modifier @tab Description
+@item @code{A} @tab Select low 16-bits of the constant/register/memory operand.
+@item @code{B} @tab Select high 16-bits of the constant/register/memory
+operand.
+@item @code{C} @tab Select bits 32-47 of the constant/register/memory operand.
+@item @code{D} @tab Select bits 48-63 of the constant/register/memory operand.
+@item @code{H} @tab Equivalent to @code{B} (for backwards compatibility).
+@item @code{I} @tab Print the inverse (logical @code{NOT}) of the constant
+value.
+@item @code{J} @tab Print an integer without a @code{#} prefix.
+@item @code{L} @tab Equivalent to @code{A} (for backwards compatibility).
+@item @code{O} @tab Offset of the current frame from the top of the stack.
+@item @code{Q} @tab Use the @code{A} instruction postfix.
+@item @code{R} @tab Inverse of condition code, for unsigned comparisons.
+@item @code{W} @tab Subtract 16 from the constant value.
+@item @code{X} @tab Use the @code{X} instruction postfix.
+@item @code{Y} @tab Subtract 4 from the constant value.
+@item @code{Z} @tab Subtract 1 from the constant value.
+@item @code{b} @tab Append @code{.B}, @code{.W} or @code{.A} to the
+instruction, depending on the mode.
+@item @code{d} @tab Offset 1 byte of a memory reference or constant value.
+@item @code{e} @tab Offset 3 bytes of a memory reference or constant value.
+@item @code{f} @tab Offset 5 bytes of a memory reference or constant value.
+@item @code{g} @tab Offset 7 bytes of a memory reference or constant value.
+@item @code{p} @tab Print the value of 2, raised to the power of the given
+constant. Used to select the specified bit position.
+@item @code{r} @tab Inverse of condition code, for signed comparisons.
+@item @code{x} @tab Equivalent to @code{X}, but only for pointers.
+@end multitable
+
+@anchor{loongarchOperandmodifiers}
+@subsubsection LoongArch Operand Modifiers
+
+The list below describes the supported modifiers and their effects for LoongArch.
+
+@multitable @columnfractions .10 .90
+@headitem Modifier @tab Description
+@item @code{d} @tab Same as @code{c}.
+@item @code{i} @tab Print the character ''@code{i}'' if the operand is not a register.
+@item @code{m} @tab Same as @code{c}, but the printed value is @code{operand - 1}.
+@item @code{u} @tab Print a LASX register.
+@item @code{w} @tab Print a LSX register.
+@item @code{X} @tab Print a constant integer operand in hexadecimal.
+@item @code{z} @tab Print the operand in its unmodified form, followed by a comma.
+@end multitable
+
+References to input and output operands in the assembler template of extended
+asm statements can use modifiers to affect the way the operands are formatted
+in the code output to the assembler. For example, the following code uses the
+'w' modifier for LoongArch:
+
+@example
+test-asm.c:
+
+#include <lsxintrin.h>
+
+__m128i foo (void)
+@{
+__m128i a,b,c;
+__asm__ ("vadd.d %w0,%w1,%w2\n\t"
+ :"=f" (c)
+ :"f" (a),"f" (b));
+
+return c;
+@}
+
+@end example
+
+@noindent
+The compile command for the test case is as follows:
+
+@example
+gcc test-asm.c -mlsx -S -o test-asm.s
+@end example
+
+@noindent
+The assembly statement produces the following assembly code:
+
+@example
+vadd.d $vr0,$vr0,$vr1
+@end example
+
+This is a 128-bit vector addition instruction, @code{c} (referred to in the
+template string as %0) is the output, and @code{a} (%1) and @code{b} (%2) are
+the inputs. @code{__m128i} is a vector data type defined in the file
+@code{lsxintrin.h} (@xref{LoongArch SX Vector Intrinsics}). The symbol '=f'
+represents a constraint using a floating-point register as an output type, and
+the 'f' in the input operand represents a constraint using a floating-point
+register operand, which can refer to the definition of a constraint
+(@xref{Constraints}) in gcc.
+
+@anchor{riscvOperandmodifiers}
+@subsubsection RISC-V Operand Modifiers
+
+The list below describes the supported modifiers and their effects for RISC-V.
+
+@multitable @columnfractions .10 .90
+@headitem Modifier @tab Description
+@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).
+@end multitable
+
+@anchor{shOperandmodifiers}
+@subsubsection SH Operand Modifiers
+
+The list below describes the supported modifiers and their effects for the SH family of processors.
+
+@multitable @columnfractions .10 .90
+@headitem Modifier @tab Description
+@item @code{.} @tab Print ''@code{.s}'' if the instruction needs a delay slot.
+@item @code{,} @tab Print ''@code{LOCAL_LABEL_PREFIX}''.
+@item @code{@@} @tab Print ''@code{trap}'', ''@code{rte}'' or ''@code{rts}'' depending on the interrupt pragma used.
+@item @code{#} @tab Print ''@code{nop}'' if there is nothing to put in the delay slot.
+@item @code{'} @tab Print likelihood suffix (''@code{/u}'' for unlikely).
+@item @code{>} @tab Print branch target if ''@code{-fverbose-asm}''.
+@item @code{O} @tab Require a constant operand and print the constant expression with no punctuation.
+@item @code{R} @tab Print the ''@code{LSW}'' of a dp value - changes if in little endian.
+@item @code{S} @tab Print the ''@code{MSW}'' of a dp value - changes if in little endian.
+@item @code{T} @tab Print the next word of a dp value - same as ''@code{R}'' in big endian mode.
+@item @code{M} @tab Print ''@code{.b }'', ''@code{.w}'', ''@code{.l}'', ''@code{.s}'', ''@code{.d}'', suffix if operand is a MEM.
+@item @code{N} @tab Print ''@code{r63}'' if the operand is ''@code{const_int 0}''.
+@item @code{d} @tab Print a ''@code{V2SF}'' as ''@code{dN}'' instead of ''@code{fpN}''.
+@item @code{m} @tab Print the pair ''@code{base,offset}'' or ''@code{base,index}'' for LD and ST.
+@item @code{U} @tab Like ''@code{%m}'' for ''@code{LD}'' and ''@code{ST}'', ''@code{HI}'' and ''@code{LO}''.
+@item @code{V} @tab Print the position of a single bit set.
+@item @code{W} @tab Print the position of a single bit cleared.
+@item @code{t} @tab Print a memory address which is a register.
+@item @code{u} @tab Print the lowest 16 bits of ''@code{CONST_INT}'', as an unsigned value.
+@item @code{o} @tab Print an operator.
+@end multitable
+
+@lowersections
+@include md.texi
+@raisesections
+
+@node Asm constexprs
+@subsection C++11 Constant Expressions instead of String Literals
+
+In C++ with @option{-std=gnu++11} or later, strings that appear in asm
+syntax---specifically, the assembler template, constraints, and
+clobbers---can be specified as parenthesized compile-time constant
+expressions as well as by string literals. The parentheses around such
+an expression are a required part of the syntax. The constant expression
+can return a container with @code{data ()} and @code{size ()}
+member functions, following similar rules as the C++26 @code{static_assert}
+message. Any string is converted to the character set of the source code.
+When this feature is available the @code{__GXX_CONSTEXPR_ASM__} preprocessor
+macro is predefined.
+
+This extension is supported for both the basic and extended asm syntax.
+
+@example
+#include <string>
+constexpr std::string_view genfoo() @{ return "foo"; @}
+
+void function()
+@{
+ asm((genfoo()));
+@}
+@end example
+
+@node Asm Labels
+@subsection Controlling Names Used in Assembler Code
+@cindex assembler names for identifiers
+@cindex names used in assembler code
+@cindex identifiers, names in assembler code
+
+You can specify the name to be used in the assembler code for a C
+function or variable by writing the @code{asm} (or @code{__asm__})
+keyword after the declarator.
+It is up to you to make sure that the assembler names you choose do not
+conflict with any other assembler symbols, or reference registers.
+
+@subsubheading Assembler names for data
+
+This sample shows how to specify the assembler name for data:
+
+@smallexample
+int foo asm ("myfoo") = 2;
+@end smallexample
+
+@noindent
+This specifies that the name to be used for the variable @code{foo} in
+the assembler code should be @samp{myfoo} rather than the usual
+@samp{_foo}.
+
+On systems where an underscore is normally prepended to the name of a C
+variable, this feature allows you to define names for the
+linker that do not start with an underscore.
+
+GCC does not support using this feature with a non-static local variable
+since such variables do not have assembler names. If you are
+trying to put the variable in a particular register, see
+@ref{Explicit Register Variables}.
+
+@subsubheading Assembler names for functions
+
+To specify the assembler name for functions, write a declaration for the
+function before its definition and put @code{asm} there, like this:
+
+@smallexample
+int func (int x, int y) asm ("MYFUNC");
+
+int func (int x, int y)
+@{
+ /* @r{@dots{}} */
+@end smallexample
+
+@noindent
+This specifies that the name to be used for the function @code{func} in
+the assembler code should be @code{MYFUNC}.
+
+@node Explicit Register Variables
+@subsection Variables in Specified Registers
+@anchor{Explicit Reg Vars}
+@cindex explicit register variables
+@cindex variables in specified registers
+@cindex specified registers
+
+GNU C allows you to associate specific hardware registers with C
+variables. In almost all cases, allowing the compiler to assign
+registers produces the best code. However under certain unusual
+circumstances, more precise control over the variable storage is
+required.
+
+Both global and local variables can be associated with a register. The
+consequences of performing this association are very different between
+the two, as explained in the sections below.
+
+@menu
+* Global Register Variables:: Variables declared at global scope.
+* Local Register Variables:: Variables declared within a function.
+@end menu
+
+@node Global Register Variables
+@subsubsection Defining Global Register Variables
+@anchor{Global Reg Vars}
+@cindex global register variables
+@cindex registers, global variables in
+@cindex registers, global allocation
+
+You can define a global register variable and associate it with a specified
+register like this:
+
+@smallexample
+register int *foo asm ("r12");
+@end smallexample
+
+@noindent
+Here @code{r12} is the name of the register that should be used. Note that
+this is the same syntax used for defining local register variables, but for
+a global variable the declaration appears outside a function. The
+@code{register} keyword is required, and cannot be combined with
+@code{static}. The register name must be a valid register name for the
+target platform.
+
+Do not use type qualifiers such as @code{const} and @code{volatile}, as
+the outcome may be contrary to expectations. In particular, using the
+@code{volatile} qualifier does not fully prevent the compiler from
+optimizing accesses to the register.
+
+Registers are a scarce resource on most systems and allowing the
+compiler to manage their usage usually results in the best code. However,
+under special circumstances it can make sense to reserve some globally.
+For example this may be useful in programs such as programming language
+interpreters that have a couple of global variables that are accessed
+very often.
+
+After defining a global register variable, for the current compilation
+unit:
+
+@itemize @bullet
+@item If the register is a call-saved register, call ABI is affected:
+the register will not be restored in function epilogue sequences after
+the variable has been assigned. Therefore, functions cannot safely
+return to callers that assume standard ABI.
+@item Conversely, if the register is a call-clobbered register, making
+calls to functions that use standard ABI may lose contents of the variable.
+Such calls may be created by the compiler even if none are evident in
+the original program, for example when libgcc functions are used to
+make up for unavailable instructions.
+@item Accesses to the variable may be optimized as usual and the register
+remains available for allocation and use in any computations, provided that
+observable values of the variable are not affected.
+@item If the variable is referenced in inline assembly, the type of access
+must be provided to the compiler via constraints (@pxref{Constraints}).
+Accesses from basic asms are not supported.
+@end itemize
+
+Note that these points @emph{only} apply to code that is compiled with the
+definition. The behavior of code that is merely linked in (for example
+code from libraries) is not affected.
+
+If you want to recompile source files that do not actually use your global
+register variable so they do not use the specified register for any other
+purpose, you need not actually add the global register declaration to
+their source code. It suffices to specify the compiler option
+@option{-ffixed-@var{reg}} (@pxref{Code Gen Options}) to reserve the
+register.
+
+@subsubheading Declaring the variable
+
+Global register variables cannot have initial values, because an
+executable file has no means to supply initial contents for a register.
+
+When selecting a register, choose one that is normally saved and
+restored by function calls on your machine. This ensures that code
+which is unaware of this reservation (such as library routines) will
+restore it before returning.
+
+On machines with register windows, be sure to choose a global
+register that is not affected magically by the function call mechanism.
+
+@subsubheading Using the variable
+
+@cindex @code{qsort}, and global register variables
+When calling routines that are not aware of the reservation, be
+cautious if those routines call back into code which uses them. As an
+example, if you call the system library version of @code{qsort}, it may
+clobber your registers during execution, but (if you have selected
+appropriate registers) it will restore them before returning. However
+it will @emph{not} restore them before calling @code{qsort}'s comparison
+function. As a result, global values will not reliably be available to
+the comparison function unless the @code{qsort} function itself is rebuilt.
+
+Similarly, it is not safe to access the global register variables from signal
+handlers or from more than one thread of control. Unless you recompile
+them specially for the task at hand, the system library routines may
+temporarily use the register for other things. Furthermore, since the register
+is not reserved exclusively for the variable, accessing it from handlers of
+asynchronous signals may observe unrelated temporary values residing in the
+register.
+
+@cindex register variable after @code{longjmp}
+@cindex global register after @code{longjmp}
+@cindex value after @code{longjmp}
+@findex longjmp
+@findex setjmp
+On most machines, @code{longjmp} restores to each global register
+variable the value it had at the time of the @code{setjmp}. On some
+machines, however, @code{longjmp} does not change the value of global
+register variables. To be portable, the function that called @code{setjmp}
+should make other arrangements to save the values of the global register
+variables, and to restore them in a @code{longjmp}. This way, the same
+thing happens regardless of what @code{longjmp} does.
+
+@node Local Register Variables
+@subsubsection Specifying Registers for Local Variables
+@anchor{Local Reg Vars}
+@cindex local variables, specifying registers
+@cindex specifying registers for local variables
+@cindex registers for local variables
+
+You can define a local register variable and associate it with a specified
+register like this:
+
+@smallexample
+register int *foo asm ("r12");
+@end smallexample
+
+@noindent
+Here @code{r12} is the name of the register that should be used. Note
+that this is the same syntax used for defining global register variables,
+but for a local variable the declaration appears within a function. The
+@code{register} keyword is required, and cannot be combined with
+@code{static}. The register name must be a valid register name for the
+target platform.
+
+Do not use type qualifiers such as @code{const} and @code{volatile}, as
+the outcome may be contrary to expectations. In particular, when the
+@code{const} qualifier is used, the compiler may substitute the
+variable with its initializer in @code{asm} statements, which may cause
+the corresponding operand to appear in a different register.
+
+As with global register variables, it is recommended that you choose
+a register that is normally saved and restored by function calls on your
+machine, so that calls to library routines will not clobber it.
+
+The only supported use for this feature is to specify registers
+for input and output operands when calling Extended @code{asm}
+(@pxref{Extended Asm}). This may be necessary if the constraints for a
+particular machine don't provide sufficient control to select the desired
+register. To force an operand into a register, create a local variable
+and specify the register name after the variable's declaration. Then use
+the local variable for the @code{asm} operand and specify any constraint
+letter that matches the register:
+
+@smallexample
+register int *p1 asm ("r0") = @dots{};
+register int *p2 asm ("r1") = @dots{};
+register int *result asm ("r0");
+asm ("sysint" : "=r" (result) : "0" (p1), "r" (p2));
+@end smallexample
+
+@emph{Warning:} In the above example, be aware that a register (for example
+@code{r0}) can be call-clobbered by subsequent code, including function
+calls and library calls for arithmetic operators on other variables (for
+example the initialization of @code{p2}). In this case, use temporary
+variables for expressions between the register assignments:
+
+@smallexample
+int t1 = @dots{};
+register int *p1 asm ("r0") = @dots{};
+register int *p2 asm ("r1") = t1;
+register int *result asm ("r0");
+asm ("sysint" : "=r" (result) : "0" (p1), "r" (p2));
+@end smallexample
+
+Defining a register variable does not reserve the register. Other than
+when invoking the Extended @code{asm}, the contents of the specified
+register are not guaranteed. For this reason, the following uses
+are explicitly @emph{not} supported. If they appear to work, it is only
+happenstance, and may stop working as intended due to (seemingly)
+unrelated changes in surrounding code, or even minor changes in the
+optimization of a future version of gcc:
+
+@itemize @bullet
+@item Passing parameters to or from Basic @code{asm}
+@item Passing parameters to or from Extended @code{asm} without using input
+or output operands.
+@item Passing parameters to or from routines written in assembler (or
+other languages) using non-standard calling conventions.
+@end itemize
+
+Some developers use Local Register Variables in an attempt to improve
+gcc's allocation of registers, especially in large functions. In this
+case the register name is essentially a hint to the register allocator.
+While in some instances this can generate better code, improvements are
+subject to the whims of the allocator/optimizers. Since there are no
+guarantees that your improvements won't be lost, this usage of Local
+Register Variables is discouraged.
+
+On the MIPS platform, there is related use for local register variables
+with slightly different characteristics (@pxref{MIPS Coprocessors,,
+Defining coprocessor specifics for MIPS targets, gccint,
+GNU Compiler Collection (GCC) Internals}).
+
+@node Size of an asm
+@subsection Size of an @code{asm}
+
+Some targets require that GCC track the size of each instruction used
+in order to generate correct code. Because the final length of the
+code produced by an @code{asm} statement is only known by the
+assembler, GCC must make an estimate as to how big it will be. It
+does this by counting the number of instructions in the pattern of the
+@code{asm} and multiplying that by the length of the longest
+instruction supported by that processor. (When working out the number
+of instructions, it assumes that any occurrence of a newline or of
+whatever statement separator character is supported by the assembler ---
+typically @samp{;} --- indicates the end of an instruction.)
+
+Normally, GCC's estimate is adequate to ensure that correct
+code is generated, but it is possible to confuse the compiler if you use
+pseudo instructions or assembler macros that expand into multiple real
+instructions, or if you use assembler directives that expand to more
+space in the object file than is needed for a single instruction.
+If this happens then the assembler may produce a diagnostic saying that
+a label is unreachable.
+
+@cindex @code{asm inline}
+This size is also used for inlining decisions. If you use @code{asm inline}
+instead of just @code{asm}, then for inlining purposes the size of the asm
+is taken as the minimum size, ignoring how many instructions GCC thinks it is.
+
+@node Syntax Extensions
+@section Other Extensions to C Syntax
+
+GNU C has traditionally supported numerous extensions to standard C
+syntax. Some of these features were originally intended for
+compatibility with other compilers or to ease traditional C
+compatibility, some have been adopted into subsequent versions of the
+C and/or C++ standards, while others remain specific to GNU C.
+
+@menu
+* Statement Exprs:: Putting statements and declarations inside expressions.
+* Local Labels:: Labels local to a block.
+* Labels as Values:: Getting pointers to labels, and computed gotos.
+* Nested Functions:: Nested functions in 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.
+* 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.
+* Mixed Labels and Declarations:: Mixing declarations, labels and code.
+* C++ Comments:: C++ comments are recognized.
+* Escaped Newlines:: Slightly looser rules for escaped newlines.
+* Hex Floats:: Hexadecimal floating-point constants.
+* 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}.
+* Alternate Keywords:: @code{__const__}, @code{__asm__}, etc., for header files.
+* Function Names:: Printable strings which are the name of the current
+ function.
+@end menu
+
+@node Statement Exprs
+@subsection Statements and Declarations in Expressions
+@cindex statements inside expressions
+@cindex declarations inside expressions
+@cindex expressions containing statements
+@cindex macros, statements in expressions
+
+@c the above section title wrapped and causes an underfull hbox.. i
+@c changed it from "within" to "in". --mew 4feb93
+A compound statement enclosed in parentheses may appear as an expression
+in GNU C@. This allows you to use loops, switches, and local variables
+within an expression.
+
+Recall that a compound statement is a sequence of statements surrounded
+by braces; in this construct, parentheses go around the braces. For
+example:
+
+@smallexample
+(@{ int y = foo (); int z;
+ if (y > 0) z = y;
+ else z = - y;
+ z; @})
+@end smallexample
+
+@noindent
+is a valid (though slightly more complex than necessary) expression
+for the absolute value of @code{foo ()}.
+
+The last thing in the compound statement should be an expression
+followed by a semicolon; the value of this subexpression serves as the
+value of the entire construct. (If you use some other kind of statement
+last within the braces, the construct has type @code{void}, and thus
+effectively no value.)
+
+This feature is especially useful in making macro definitions ``safe'' (so
+that they evaluate each operand exactly once). For example, the
+``maximum'' function is commonly defined as a macro in standard C as
+follows:
+
+@smallexample
+#define max(a,b) ((a) > (b) ? (a) : (b))
+@end smallexample
+
+@noindent
+@cindex side effects, macro argument
+But this definition computes either @var{a} or @var{b} twice, with bad
+results if the operand has side effects. In GNU C, if you know the
+type of the operands (here taken as @code{int}), you can avoid this
+problem by defining the macro as follows:
+
+@smallexample
+#define maxint(a,b) \
+ (@{int _a = (a), _b = (b); _a > _b ? _a : _b; @})
+@end smallexample
+
+Note that introducing variable declarations (as we do in @code{maxint}) can
+cause variable shadowing, so while this example using the @code{max} macro
+produces correct results:
+@smallexample
+int _a = 1, _b = 2, c;
+c = max (_a, _b);
+@end smallexample
+@noindent
+this example using maxint will not:
+@smallexample
+int _a = 1, _b = 2, c;
+c = maxint (_a, _b);
+@end smallexample
+
+This problem may for instance occur when we use this pattern recursively, like
+so:
+
+@smallexample
+#define maxint3(a, b, c) \
+ (@{int _a = (a), _b = (b), _c = (c); maxint (maxint (_a, _b), _c); @})
+@end smallexample
+
+Embedded statements are not allowed in constant expressions, such as
+the value of an enumeration constant, the width of a bit-field, or
+the initial value of a static variable.
+
+If you don't know the type of the operand, you can still do this, but you
+must use @code{typeof} or @code{__auto_type} (@pxref{Typeof}).
+
+In G++, the result value of a statement expression undergoes array and
+function pointer decay, and is returned by value to the enclosing
+expression. For instance, if @code{A} is a class, then
+
+@smallexample
+ A a;
+
+ (@{a;@}).Foo ()
+@end smallexample
+
+@noindent
+constructs a temporary @code{A} object to hold the result of the
+statement expression, and that is used to invoke @code{Foo}.
+Therefore the @code{this} pointer observed by @code{Foo} is not the
+address of @code{a}.
+
+In a statement expression, any temporaries created within a statement
+are destroyed at that statement's end. This makes statement
+expressions inside macros slightly different from function calls. In
+the latter case temporaries introduced during argument evaluation are
+destroyed at the end of the statement that includes the function
+call. In the statement expression case they are destroyed during
+the statement expression. For instance,
+
+@smallexample
+#define macro(a) (@{__typeof__(a) b = (a); b + 3; @})
+template<typename T> T function(T a) @{ T b = a; return b + 3; @}
+
+void foo ()
+@{
+ macro (X ());
+ function (X ());
+@}
+@end smallexample
+
+@noindent
+has different places where temporaries are destroyed. For the
+@code{macro} case, the temporary @code{X} is destroyed just after
+the initialization of @code{b}. In the @code{function} case that
+temporary is destroyed when the function returns.
+
+These considerations mean that it is probably a bad idea to use
+statement expressions of this form in header files that are designed to
+work with C++. (Note that some versions of the GNU C Library contained
+header files using statement expressions that lead to precisely this
+bug.)
+
+Jumping into a statement expression with @code{goto} or using a
+@code{switch} statement outside the statement expression with a
+@code{case} or @code{default} label inside the statement expression is
+not permitted. Jumping into a statement expression with a computed
+@code{goto} (@pxref{Labels as Values}) has undefined behavior.
+Jumping out of a statement expression is permitted, but if the
+statement expression is part of a larger expression then it is
+unspecified which other subexpressions of that expression have been
+evaluated except where the language definition requires certain
+subexpressions to be evaluated before or after the statement
+expression. A @code{break} or @code{continue} statement inside of
+a statement expression used in @code{while}, @code{do} or @code{for}
+loop or @code{switch} statement condition
+or @code{for} statement init or increment expressions jumps to an
+outer loop or @code{switch} statement if any (otherwise it is an error),
+rather than to the loop or @code{switch} statement in whose condition
+or init or increment expression it appears.
+In any case, as with a function call, the evaluation of a
+statement expression is not interleaved with the evaluation of other
+parts of the containing expression. For example,
+
+@smallexample
+ foo (), ((@{ bar1 (); goto a; 0; @}) + bar2 ()), baz();
+@end smallexample
+
+@noindent
+calls @code{foo} and @code{bar1} and does not call @code{baz} but
+may or may not call @code{bar2}. If @code{bar2} is called, it is
+called after @code{foo} and before @code{bar1}.
+
+@node Local Labels
+@subsection Locally Declared Labels
+@cindex local labels
+@cindex macros, local labels
+
+GCC allows you to declare @dfn{local labels} in any nested block
+scope. A local label is just like an ordinary label, but you can
+only reference it (with a @code{goto} statement, or by taking its
+address) within the block in which it is declared.
+
+A local label declaration looks like this:
+
+@smallexample
+__label__ @var{label};
+@end smallexample
+
+@noindent
+or
+
+@smallexample
+__label__ @var{label1}, @var{label2}, /* @r{@dots{}} */;
+@end smallexample
+
+Local label declarations must come at the beginning of the block,
+before any ordinary declarations or statements.
+
+The label declaration defines the label @emph{name}, but does not define
+the label itself. You must do this in the usual way, with
+@code{@var{label}:}, within the statements of the statement expression.
+
+The local label feature is useful for complex macros. If a macro
+contains nested loops, a @code{goto} can be useful for breaking out of
+them. However, an ordinary label whose scope is the whole function
+cannot be used: if the macro can be expanded several times in one
+function, the label is multiply defined in that function. A
+local label avoids this problem. For example:
+
+@smallexample
+#define SEARCH(value, array, target) \
+do @{ \
+ __label__ found; \
+ typeof (target) _SEARCH_target = (target); \
+ typeof (*(array)) *_SEARCH_array = (array); \
+ int i, j; \
+ int value; \
+ for (i = 0; i < max; i++) \
+ for (j = 0; j < max; j++) \
+ if (_SEARCH_array[i][j] == _SEARCH_target) \
+ @{ (value) = i; goto found; @} \
+ (value) = -1; \
+ found:; \
+@} while (0)
+@end smallexample
+
+This could also be written using a statement expression:
+
+@smallexample
+#define SEARCH(array, target) \
+(@{ \
+ __label__ found; \
+ typeof (target) _SEARCH_target = (target); \
+ typeof (*(array)) *_SEARCH_array = (array); \
+ int i, j; \
+ int value; \
+ for (i = 0; i < max; i++) \
+ for (j = 0; j < max; j++) \
+ if (_SEARCH_array[i][j] == _SEARCH_target) \
+ @{ value = i; goto found; @} \
+ value = -1; \
+ found: \
+ value; \
+@})
+@end smallexample
+
+Local label declarations also make the labels they declare visible to
+nested functions, if there are any. @xref{Nested Functions}, for details.
+
+@node Labels as Values
+@subsection Labels as Values
+@cindex labels as values
+@cindex computed gotos
+@cindex goto with computed label
+@cindex address of a label
+
+You can get the address of a label defined in the current function
+(or a containing function) with the unary operator @samp{&&}. The
+value has type @code{void *}. This value is a constant and can be used
+wherever a constant of that type is valid. For example:
+
+@smallexample
+void *ptr;
+/* @r{@dots{}} */
+ptr = &&foo;
+@end smallexample
+
+To use these values, you need to be able to jump to one. This is done
+with the computed goto statement@footnote{The analogous feature in
+Fortran is called an assigned goto, but that name seems inappropriate in
+C, where one can do more than simply store label addresses in label
+variables.}, @code{goto *@var{exp};}. For example,
+
+@smallexample
+goto *ptr;
+@end smallexample
+
+@noindent
+Any expression of type @code{void *} is allowed.
+
+One way of using these constants is in initializing a static array that
+serves as a jump table:
+
+@smallexample
+static void *array[] = @{ &&foo, &&bar, &&hack @};
+@end smallexample
+
+@noindent
+Then you can select a label with indexing, like this:
+
+@smallexample
+goto *array[i];
+@end smallexample
+
+@noindent
+Note that this does not check whether the subscript is in bounds---array
+indexing in C never does that.
+
+Such an array of label values serves a purpose much like that of the
+@code{switch} statement. The @code{switch} statement is cleaner, so
+use that rather than an array unless the problem does not fit a
+@code{switch} statement very well.
+
+Another use of label values is in an interpreter for threaded code.
+The labels within the interpreter function can be stored in the
+threaded code for super-fast dispatching.
+
+You may not use this mechanism to jump to code in a different function.
+If you do that, totally unpredictable things happen. The best way to
+avoid this is to store the label address only in automatic variables and
+never pass it as an argument.
+
+An alternate way to write the above example is
+
+@smallexample
+static const int array[] = @{ &&foo - &&foo, &&bar - &&foo,
+ &&hack - &&foo @};
+goto *(&&foo + array[i]);
+@end smallexample
+
+@noindent
+This is more friendly to code living in shared libraries, as it reduces
+the number of dynamic relocations that are needed, and by consequence,
+allows the data to be read-only.
+This alternative with label differences is not supported for the AVR target,
+please use the first approach for AVR programs.
+
+The @code{&&foo} expressions for the same label might have different
+values if the containing function is inlined or cloned. If a program
+relies on them being always the same,
+@code{__attribute__((__noinline__,__noclone__))} should be used to
+prevent inlining and cloning. If @code{&&foo} is used in a static
+variable initializer, inlining and cloning is forbidden.
+
+Unlike a normal goto, in GNU C++ a computed goto will not call
+destructors for objects that go out of scope.
+
+@node Nested Functions
+@subsection Nested Functions
+@cindex nested functions
+@cindex downward funargs
+@cindex thunks
+
+A @dfn{nested function} is a function defined inside another function.
+Nested functions are supported as an extension in GNU C, but are not
+supported by GNU C++.
+
+The nested function's name is local to the block where it is defined.
+For example, here we define a nested function named @code{square}, and
+call it twice:
+
+@smallexample
+@group
+foo (double a, double b)
+@{
+ double square (double z) @{ return z * z; @}
+
+ return square (a) + square (b);
+@}
+@end group
+@end smallexample
+
+The nested function can access all the variables of the containing
+function that are visible at the point of its definition. This is
+called @dfn{lexical scoping}. For example, here we show a nested
+function which uses an inherited variable named @code{offset}:
+
+@smallexample
+@group
+bar (int *array, int offset, int size)
+@{
+ int access (int *array, int index)
+ @{ return array[index + offset]; @}
+ int i;
+ /* @r{@dots{}} */
+ for (i = 0; i < size; i++)
+ /* @r{@dots{}} */ access (array, i) /* @r{@dots{}} */
+@}
+@end group
+@end smallexample
+
+Nested function definitions are permitted within functions in the places
+where variable definitions are allowed; that is, in any block, mixed
+with the other declarations and statements in the block.
+
+It is possible to call the nested function from outside the scope of its
+name by storing its address or passing the address to another function:
+
+@smallexample
+hack (int *array, int size)
+@{
+ void store (int index, int value)
+ @{ array[index] = value; @}
+
+ intermediate (store, size);
+@}
+@end smallexample
+
+Here, the function @code{intermediate} receives the address of
+@code{store} as an argument. If @code{intermediate} calls @code{store},
+the arguments given to @code{store} are used to store into @code{array}.
+But this technique works only so long as the containing function
+(@code{hack}, in this example) does not exit.
+
+If you try to call the nested function through its address after the
+containing function exits, all hell breaks loose. If you try
+to call it after a containing scope level exits, and if it refers
+to some of the variables that are no longer in scope, you may be lucky,
+but it's not wise to take the risk. If, however, the nested function
+does not refer to anything that has gone out of scope, you should be
+safe.
+
+GCC implements taking the address of a nested function using a technique
+called @dfn{trampolines}. This technique was described in
+@cite{Lexical Closures for C++} (Thomas M. Breuel, USENIX
+C++ Conference Proceedings, October 17-21, 1988).
+
+A nested function can jump to a label inherited from a containing
+function, provided the label is explicitly declared in the containing
+function (@pxref{Local Labels}). Such a jump returns instantly to the
+containing function, exiting the nested function that did the
+@code{goto} and any intermediate functions as well. Here is an example:
+
+@smallexample
+@group
+bar (int *array, int offset, int size)
+@{
+ __label__ failure;
+ int access (int *array, int index)
+ @{
+ if (index > size)
+ goto failure;
+ return array[index + offset];
+ @}
+ int i;
+ /* @r{@dots{}} */
+ for (i = 0; i < size; i++)
+ /* @r{@dots{}} */ access (array, i) /* @r{@dots{}} */
+ /* @r{@dots{}} */
+ return 0;
+
+ /* @r{Control comes here from @code{access}
+ if it detects an error.} */
+ failure:
+ return -1;
+@}
+@end group
+@end smallexample
+
+A nested function always has no linkage. Declaring one with
+@code{extern} or @code{static} is erroneous. If you need to declare the nested function
+before its definition, use @code{auto} (which is otherwise meaningless
+for function declarations).
+
+@smallexample
+bar (int *array, int offset, int size)
+@{
+ __label__ failure;
+ auto int access (int *, int);
+ /* @r{@dots{}} */
+ int access (int *array, int index)
+ @{
+ if (index > size)
+ goto failure;
+ return array[index + offset];
+ @}
+ /* @r{@dots{}} */
+@}
+@end smallexample
+
+@node Typeof
+@subsection Referring to a Type with @code{typeof}
+@findex typeof
+@findex sizeof
+@cindex macros, types of arguments
-All implicitly popped input registers must be closer to the top of
-the reg-stack than any input that is not implicitly popped.
+Another way to refer to the type of an expression is with @code{typeof}.
+The syntax of using of this keyword looks like @code{sizeof}, but the
+construct acts semantically like a type name defined with @code{typedef}.
-It is possible that if an input dies in an @code{asm}, the compiler might
-use the input register for an output reload. Consider this example:
+There are two ways of writing the argument to @code{typeof}: with an
+expression or with a type. Here is an example with an expression:
@smallexample
-asm ("foo" : "=t" (a) : "f" (b));
+typeof (x[0](1))
@end smallexample
@noindent
-This code says that input @code{b} is not popped by the @code{asm}, and that
-the @code{asm} pushes a result onto the reg-stack, i.e., the stack is one
-deeper after the @code{asm} than it was before. But, it is possible that
-reload may think that it can use the same register for both the input and
-the output.
-
-To prevent this from happening,
-if any input operand uses the @samp{f} constraint, all output register
-constraints must use the @samp{&} early-clobber modifier.
+This assumes that @code{x} is an array of pointers to functions;
+the type described is that of the values of the functions.
-The example above is correctly written as:
+Here is an example with a typename as the argument:
@smallexample
-asm ("foo" : "=&t" (a) : "f" (b));
+typeof (int *)
@end smallexample
-@item
-Some operands need to be in particular places on the stack. All
-output operands fall in this category---GCC has no other way to
-know which registers the outputs appear in unless you indicate
-this in the constraints.
-
-Output operands must specifically indicate which register an output
-appears in after an @code{asm}. @samp{=f} is not allowed: the operand
-constraints must select a class with a single register.
-
-@item
-Output operands may not be ``inserted'' between existing stack registers.
-Since no 387 opcode uses a read/write operand, all output operands
-are dead before the @code{asm}, and are pushed by the @code{asm}.
-It makes no sense to push anywhere but the top of the reg-stack.
+@noindent
+Here the type described is that of pointers to @code{int}.
-Output operands must start at the top of the reg-stack: output
-operands may not ``skip'' a register.
+If you are writing a header file that must work when included in ISO C
+programs, write @code{__typeof__} instead of @code{typeof}.
+@xref{Alternate Keywords}.
-@item
-Some @code{asm} statements may need extra stack space for internal
-calculations. This can be guaranteed by clobbering stack registers
-unrelated to the inputs and outputs.
+A @code{typeof} construct can be used anywhere a typedef name can be
+used. For example, you can use it in a declaration, in a cast, or inside
+of @code{sizeof} or @code{typeof}.
-@end enumerate
+The operand of @code{typeof} is evaluated for its side effects if and
+only if it is an expression of variably modified type or the name of
+such a type.
-This @code{asm}
-takes one input, which is internally popped, and produces two outputs.
+@code{typeof} is often useful in conjunction with
+statement expressions (@pxref{Statement Exprs}).
+Here is how the two together can
+be used to define a safe ``maximum'' macro which operates on any
+arithmetic type and evaluates each of its arguments exactly once:
@smallexample
-asm ("fsincos" : "=t" (cos), "=u" (sin) : "0" (inp));
+#define max(a,b) \
+ (@{ typeof (a) _a = (a); \
+ typeof (b) _b = (b); \
+ _a > _b ? _a : _b; @})
@end smallexample
-@noindent
-This @code{asm} takes two inputs, which are popped by the @code{fyl2xp1} opcode,
-and replaces them with one output. The @code{st(1)} clobber is necessary
-for the compiler to know that @code{fyl2xp1} pops both inputs.
-
-@smallexample
-asm ("fyl2xp1" : "=t" (result) : "0" (x), "u" (y) : "st(1)");
-@end smallexample
+@cindex underscores in variables in macros
+@cindex @samp{_} in variables in macros
+@cindex local variables in macros
+@cindex variables, local, in macros
+@cindex macros, local variables in
-@anchor{msp430Operandmodifiers}
-@subsubsection MSP430 Operand Modifiers
+The reason for using names that start with underscores for the local
+variables is to avoid conflicts with variable names that occur within the
+expressions that are substituted for @code{a} and @code{b}. Eventually we
+hope to design a new form of declaration syntax that allows you to declare
+variables whose scopes start only after their initializers; this will be a
+more reliable way to prevent such conflicts.
-The list below describes the supported modifiers and their effects for MSP430.
+@noindent
+Some more examples of the use of @code{typeof}:
-@multitable @columnfractions .10 .90
-@headitem Modifier @tab Description
-@item @code{A} @tab Select low 16-bits of the constant/register/memory operand.
-@item @code{B} @tab Select high 16-bits of the constant/register/memory
-operand.
-@item @code{C} @tab Select bits 32-47 of the constant/register/memory operand.
-@item @code{D} @tab Select bits 48-63 of the constant/register/memory operand.
-@item @code{H} @tab Equivalent to @code{B} (for backwards compatibility).
-@item @code{I} @tab Print the inverse (logical @code{NOT}) of the constant
-value.
-@item @code{J} @tab Print an integer without a @code{#} prefix.
-@item @code{L} @tab Equivalent to @code{A} (for backwards compatibility).
-@item @code{O} @tab Offset of the current frame from the top of the stack.
-@item @code{Q} @tab Use the @code{A} instruction postfix.
-@item @code{R} @tab Inverse of condition code, for unsigned comparisons.
-@item @code{W} @tab Subtract 16 from the constant value.
-@item @code{X} @tab Use the @code{X} instruction postfix.
-@item @code{Y} @tab Subtract 4 from the constant value.
-@item @code{Z} @tab Subtract 1 from the constant value.
-@item @code{b} @tab Append @code{.B}, @code{.W} or @code{.A} to the
-instruction, depending on the mode.
-@item @code{d} @tab Offset 1 byte of a memory reference or constant value.
-@item @code{e} @tab Offset 3 bytes of a memory reference or constant value.
-@item @code{f} @tab Offset 5 bytes of a memory reference or constant value.
-@item @code{g} @tab Offset 7 bytes of a memory reference or constant value.
-@item @code{p} @tab Print the value of 2, raised to the power of the given
-constant. Used to select the specified bit position.
-@item @code{r} @tab Inverse of condition code, for signed comparisons.
-@item @code{x} @tab Equivalent to @code{X}, but only for pointers.
-@end multitable
+@itemize @bullet
+@item
+This declares @code{y} with the type of what @code{x} points to.
-@anchor{loongarchOperandmodifiers}
-@subsubsection LoongArch Operand Modifiers
+@smallexample
+typeof (*x) y;
+@end smallexample
-The list below describes the supported modifiers and their effects for LoongArch.
+@item
+This declares @code{y} as an array of such values.
-@multitable @columnfractions .10 .90
-@headitem Modifier @tab Description
-@item @code{d} @tab Same as @code{c}.
-@item @code{i} @tab Print the character ''@code{i}'' if the operand is not a register.
-@item @code{m} @tab Same as @code{c}, but the printed value is @code{operand - 1}.
-@item @code{u} @tab Print a LASX register.
-@item @code{w} @tab Print a LSX register.
-@item @code{X} @tab Print a constant integer operand in hexadecimal.
-@item @code{z} @tab Print the operand in its unmodified form, followed by a comma.
-@end multitable
+@smallexample
+typeof (*x) y[4];
+@end smallexample
-References to input and output operands in the assembler template of extended
-asm statements can use modifiers to affect the way the operands are formatted
-in the code output to the assembler. For example, the following code uses the
-'w' modifier for LoongArch:
+@item
+This declares @code{y} as an array of pointers to characters:
-@example
-test-asm.c:
+@smallexample
+typeof (typeof (char *)[4]) y;
+@end smallexample
-#include <lsxintrin.h>
+@noindent
+It is equivalent to the following traditional C declaration:
-__m128i foo (void)
-@{
-__m128i a,b,c;
-__asm__ ("vadd.d %w0,%w1,%w2\n\t"
- :"=f" (c)
- :"f" (a),"f" (b));
+@smallexample
+char *y[4];
+@end smallexample
-return c;
-@}
+To see the meaning of the declaration using @code{typeof}, and why it
+might be a useful way to write, rewrite it with these macros:
-@end example
+@smallexample
+#define pointer(T) typeof(T *)
+#define array(T, N) typeof(T [N])
+@end smallexample
@noindent
-The compile command for the test case is as follows:
+Now the declaration can be rewritten this way:
-@example
-gcc test-asm.c -mlsx -S -o test-asm.s
-@end example
+@smallexample
+array (pointer (char), 4) y;
+@end smallexample
@noindent
-The assembly statement produces the following assembly code:
-
-@example
-vadd.d $vr0,$vr0,$vr1
-@end example
-
-This is a 128-bit vector addition instruction, @code{c} (referred to in the
-template string as %0) is the output, and @code{a} (%1) and @code{b} (%2) are
-the inputs. @code{__m128i} is a vector data type defined in the file
-@code{lsxintrin.h} (@xref{LoongArch SX Vector Intrinsics}). The symbol '=f'
-represents a constraint using a floating-point register as an output type, and
-the 'f' in the input operand represents a constraint using a floating-point
-register operand, which can refer to the definition of a constraint
-(@xref{Constraints}) in gcc.
-
-@anchor{riscvOperandmodifiers}
-@subsubsection RISC-V Operand Modifiers
-
-The list below describes the supported modifiers and their effects for RISC-V.
-
-@multitable @columnfractions .10 .90
-@headitem Modifier @tab Description
-@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).
-@end multitable
-
-@anchor{shOperandmodifiers}
-@subsubsection SH Operand Modifiers
-
-The list below describes the supported modifiers and their effects for the SH family of processors.
-
-@multitable @columnfractions .10 .90
-@headitem Modifier @tab Description
-@item @code{.} @tab Print ''@code{.s}'' if the instruction needs a delay slot.
-@item @code{,} @tab Print ''@code{LOCAL_LABEL_PREFIX}''.
-@item @code{@@} @tab Print ''@code{trap}'', ''@code{rte}'' or ''@code{rts}'' depending on the interrupt pragma used.
-@item @code{#} @tab Print ''@code{nop}'' if there is nothing to put in the delay slot.
-@item @code{'} @tab Print likelihood suffix (''@code{/u}'' for unlikely).
-@item @code{>} @tab Print branch target if ''@code{-fverbose-asm}''.
-@item @code{O} @tab Require a constant operand and print the constant expression with no punctuation.
-@item @code{R} @tab Print the ''@code{LSW}'' of a dp value - changes if in little endian.
-@item @code{S} @tab Print the ''@code{MSW}'' of a dp value - changes if in little endian.
-@item @code{T} @tab Print the next word of a dp value - same as ''@code{R}'' in big endian mode.
-@item @code{M} @tab Print ''@code{.b }'', ''@code{.w}'', ''@code{.l}'', ''@code{.s}'', ''@code{.d}'', suffix if operand is a MEM.
-@item @code{N} @tab Print ''@code{r63}'' if the operand is ''@code{const_int 0}''.
-@item @code{d} @tab Print a ''@code{V2SF}'' as ''@code{dN}'' instead of ''@code{fpN}''.
-@item @code{m} @tab Print the pair ''@code{base,offset}'' or ''@code{base,index}'' for LD and ST.
-@item @code{U} @tab Like ''@code{%m}'' for ''@code{LD}'' and ''@code{ST}'', ''@code{HI}'' and ''@code{LO}''.
-@item @code{V} @tab Print the position of a single bit set.
-@item @code{W} @tab Print the position of a single bit cleared.
-@item @code{t} @tab Print a memory address which is a register.
-@item @code{u} @tab Print the lowest 16 bits of ''@code{CONST_INT}'', as an unsigned value.
-@item @code{o} @tab Print an operator.
-@end multitable
+Thus, @code{array (pointer (char), 4)} is the type of arrays of 4
+pointers to @code{char}.
+@end itemize
-@lowersections
-@include md.texi
-@raisesections
+The ISO C23 operator @code{typeof_unqual} is available in ISO C23 mode
+and its result is the non-atomic unqualified version of what @code{typeof}
+operator returns. Alternate spelling @code{__typeof_unqual__} is
+available in all C modes and provides non-atomic unqualified version of
+what @code{__typeof__} operator returns.
+@xref{Alternate Keywords}.
-@node Asm constexprs
-@subsection C++11 Constant Expressions instead of String Literals
+@cindex @code{__auto_type} in GNU C
+In GNU C, but not GNU C++, you may also declare the type of a variable
+as @code{__auto_type}. In that case, the declaration must declare
+only one variable, whose declarator must just be an identifier, the
+declaration must be initialized, and the type of the variable is
+determined by the initializer; the name of the variable is not in
+scope until after the initializer. (In C++, you should use C++11
+@code{auto} for this purpose.) Using @code{__auto_type}, the
+``maximum'' macro above could be written as:
-In C++ with @option{-std=gnu++11} or later, strings that appear in asm
-syntax---specifically, the assembler template, constraints, and
-clobbers---can be specified as parenthesized compile-time constant
-expressions as well as by string literals. The parentheses around such
-an expression are a required part of the syntax. The constant expression
-can return a container with @code{data ()} and @code{size ()}
-member functions, following similar rules as the C++26 @code{static_assert}
-message. Any string is converted to the character set of the source code.
-When this feature is available the @code{__GXX_CONSTEXPR_ASM__} preprocessor
-macro is predefined.
+@smallexample
+#define max(a,b) \
+ (@{ __auto_type _a = (a); \
+ __auto_type _b = (b); \
+ _a > _b ? _a : _b; @})
+@end smallexample
-This extension is supported for both the basic and extended asm syntax.
+Using @code{__auto_type} instead of @code{typeof} has two advantages:
-@example
-#include <string>
-constexpr std::string_view genfoo() @{ return "foo"; @}
+@itemize @bullet
+@item Each argument to the macro appears only once in the expansion of
+the macro. This prevents the size of the macro expansion growing
+exponentially when calls to such macros are nested inside arguments of
+such macros.
-void function()
-@{
- asm((genfoo()));
-@}
-@end example
+@item If the argument to the macro has variably modified type, it is
+evaluated only once when using @code{__auto_type}, but twice if
+@code{typeof} is used.
+@end itemize
-@node Asm Labels
-@subsection Controlling Names Used in Assembler Code
-@cindex assembler names for identifiers
-@cindex names used in assembler code
-@cindex identifiers, names in assembler code
+@node Offsetof
+@subsection Support for @code{offsetof}
+@findex __builtin_offsetof
-You can specify the name to be used in the assembler code for a C
-function or variable by writing the @code{asm} (or @code{__asm__})
-keyword after the declarator.
-It is up to you to make sure that the assembler names you choose do not
-conflict with any other assembler symbols, or reference registers.
+GCC implements for both C and C++ a syntactic extension to implement
+the @code{offsetof} macro.
-@subsubheading Assembler names for data
+@smallexample
+primary:
+ "__builtin_offsetof" "(" @code{typename} "," offsetof_member_designator ")"
-This sample shows how to specify the assembler name for data:
+offsetof_member_designator:
+ @code{identifier}
+ | offsetof_member_designator "." @code{identifier}
+ | offsetof_member_designator "[" @code{expr} "]"
+@end smallexample
+
+This extension is sufficient such that
@smallexample
-int foo asm ("myfoo") = 2;
+#define offsetof(@var{type}, @var{member}) __builtin_offsetof (@var{type}, @var{member})
@end smallexample
@noindent
-This specifies that the name to be used for the variable @code{foo} in
-the assembler code should be @samp{myfoo} rather than the usual
-@samp{_foo}.
+is a suitable definition of the @code{offsetof} macro. In C++, @var{type}
+may be dependent. In either case, @var{member} may consist of a single
+identifier, or a sequence of member accesses and array references.
-On systems where an underscore is normally prepended to the name of a C
-variable, this feature allows you to define names for the
-linker that do not start with an underscore.
+@node Alignment
+@subsection Determining the Alignment of Functions, Types or Variables
+@cindex alignment
+@cindex type alignment
+@cindex variable alignment
-GCC does not support using this feature with a non-static local variable
-since such variables do not have assembler names. If you are
-trying to put the variable in a particular register, see
-@ref{Explicit Register Variables}.
+The keyword @code{__alignof__} determines the alignment requirement of
+a function, object, or a type, or the minimum alignment usually required
+by a type. Its syntax is just like @code{sizeof} and C11 @code{_Alignof}.
-@subsubheading Assembler names for functions
+For example, if the target machine requires a @code{double} value to be
+aligned on an 8-byte boundary, then @code{__alignof__ (double)} is 8.
+This is true on many RISC machines. On more traditional machine
+designs, @code{__alignof__ (double)} is 4 or even 2.
-To specify the assembler name for functions, write a declaration for the
-function before its definition and put @code{asm} there, like this:
+Some machines never actually require alignment; they allow references to any
+data type even at an odd address. For these machines, @code{__alignof__}
+reports the smallest alignment that GCC gives the data type, usually as
+mandated by the target ABI.
+
+If the operand of @code{__alignof__} is an lvalue rather than a type,
+its value is the required alignment for its type, taking into account
+any minimum alignment specified by attribute @code{aligned}
+(@pxref{Common Variable Attributes}). For example, after this
+declaration:
@smallexample
-int func (int x, int y) asm ("MYFUNC");
-
-int func (int x, int y)
-@{
- /* @r{@dots{}} */
+struct foo @{ int x; char y; @} foo1;
@end smallexample
@noindent
-This specifies that the name to be used for the function @code{func} in
-the assembler code should be @code{MYFUNC}.
+the value of @code{__alignof__ (foo1.y)} is 1, even though its actual
+alignment is probably 2 or 4, the same as @code{__alignof__ (int)}.
+It is an error to ask for the alignment of an incomplete type other
+than @code{void}.
-@node Explicit Register Variables
-@subsection Variables in Specified Registers
-@anchor{Explicit Reg Vars}
-@cindex explicit register variables
-@cindex variables in specified registers
-@cindex specified registers
+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}).
-GNU C allows you to associate specific hardware registers with C
-variables. In almost all cases, allowing the compiler to assign
-registers produces the best code. However under certain unusual
-circumstances, more precise control over the variable storage is
-required.
+@node Incomplete Enums
+@subsection Incomplete @code{enum} Types
-Both global and local variables can be associated with a register. The
-consequences of performing this association are very different between
-the two, as explained in the sections below.
+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.
-@menu
-* Global Register Variables:: Variables declared at global scope.
-* Local Register Variables:: Variables declared within a function.
-@end menu
+You cannot allocate variables or storage using the type while it is
+incomplete. However, you can work with pointers to that type.
-@node Global Register Variables
-@subsubsection Defining Global Register Variables
-@anchor{Global Reg Vars}
-@cindex global register variables
-@cindex registers, global variables in
-@cindex registers, global allocation
+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.
-You can define a global register variable and associate it with a specified
-register like this:
+This extension is not supported by GNU C++.
+
+@node Variadic Macros
+@subsection Macros with a Variable Number of Arguments.
+@cindex variable number of arguments
+@cindex macro with variable arguments
+@cindex rest argument (in macro)
+@cindex variadic macros
+
+In the ISO C standard of 1999, a macro can be declared to accept a
+variable number of arguments much as a function can. The syntax for
+defining the macro is similar to that of a function. Here is an
+example:
@smallexample
-register int *foo asm ("r12");
+#define debug(format, ...) fprintf (stderr, format, __VA_ARGS__)
@end smallexample
@noindent
-Here @code{r12} is the name of the register that should be used. Note that
-this is the same syntax used for defining local register variables, but for
-a global variable the declaration appears outside a function. The
-@code{register} keyword is required, and cannot be combined with
-@code{static}. The register name must be a valid register name for the
-target platform.
+Here @samp{@dots{}} is a @dfn{variable argument}. In the invocation of
+such a macro, it represents the zero or more tokens until the closing
+parenthesis that ends the invocation, including any commas. This set of
+tokens replaces the identifier @code{__VA_ARGS__} in the macro body
+wherever it appears. See the CPP manual for more information.
-Do not use type qualifiers such as @code{const} and @code{volatile}, as
-the outcome may be contrary to expectations. In particular, using the
-@code{volatile} qualifier does not fully prevent the compiler from
-optimizing accesses to the register.
+GCC has long supported variadic macros, and used a different syntax that
+allowed you to give a name to the variable arguments just like any other
+argument. Here is an example:
-Registers are a scarce resource on most systems and allowing the
-compiler to manage their usage usually results in the best code. However,
-under special circumstances it can make sense to reserve some globally.
-For example this may be useful in programs such as programming language
-interpreters that have a couple of global variables that are accessed
-very often.
+@smallexample
+#define debug(format, args...) fprintf (stderr, format, args)
+@end smallexample
-After defining a global register variable, for the current compilation
-unit:
+@noindent
+This is in all ways equivalent to the ISO C example above, but arguably
+more readable and descriptive.
-@itemize @bullet
-@item If the register is a call-saved register, call ABI is affected:
-the register will not be restored in function epilogue sequences after
-the variable has been assigned. Therefore, functions cannot safely
-return to callers that assume standard ABI.
-@item Conversely, if the register is a call-clobbered register, making
-calls to functions that use standard ABI may lose contents of the variable.
-Such calls may be created by the compiler even if none are evident in
-the original program, for example when libgcc functions are used to
-make up for unavailable instructions.
-@item Accesses to the variable may be optimized as usual and the register
-remains available for allocation and use in any computations, provided that
-observable values of the variable are not affected.
-@item If the variable is referenced in inline assembly, the type of access
-must be provided to the compiler via constraints (@pxref{Constraints}).
-Accesses from basic asms are not supported.
-@end itemize
+GNU CPP has two further variadic macro extensions, and permits them to
+be used with either of the above forms of macro definition.
+
+In standard C, you are not allowed to leave the variable argument out
+entirely; but you are allowed to pass an empty argument. For example,
+this invocation is invalid in ISO C, because there is no comma after
+the string:
+
+@smallexample
+debug ("A message")
+@end smallexample
+
+GNU CPP permits you to completely omit the variable arguments in this
+way. In the above examples, the compiler would complain, though since
+the expansion of the macro still has the extra comma after the format
+string.
+
+To help solve this problem, CPP behaves specially for variable arguments
+used with the token paste operator, @samp{##}. If instead you write
-Note that these points @emph{only} apply to code that is compiled with the
-definition. The behavior of code that is merely linked in (for example
-code from libraries) is not affected.
+@smallexample
+#define debug(format, ...) fprintf (stderr, format, ## __VA_ARGS__)
+@end smallexample
-If you want to recompile source files that do not actually use your global
-register variable so they do not use the specified register for any other
-purpose, you need not actually add the global register declaration to
-their source code. It suffices to specify the compiler option
-@option{-ffixed-@var{reg}} (@pxref{Code Gen Options}) to reserve the
-register.
+@noindent
+and if the variable arguments are omitted or empty, the @samp{##}
+operator causes the preprocessor to remove the comma before it. If you
+do provide some variable arguments in your macro invocation, GNU CPP
+does not complain about the paste operation and instead places the
+variable arguments after the comma. Just like any other pasted macro
+argument, these arguments are not macro expanded.
-@subsubheading Declaring the variable
+@node Conditionals
+@subsection Conditionals with Omitted Operands
+@cindex conditional expressions, extensions
+@cindex omitted middle-operands
+@cindex middle-operands, omitted
+@cindex extensions, @code{?:}
+@cindex @code{?:} extensions
-Global register variables cannot have initial values, because an
-executable file has no means to supply initial contents for a register.
+The middle operand in a conditional expression may be omitted. Then
+if the first operand is nonzero, its value is the value of the conditional
+expression.
-When selecting a register, choose one that is normally saved and
-restored by function calls on your machine. This ensures that code
-which is unaware of this reservation (such as library routines) will
-restore it before returning.
+Therefore, the expression
-On machines with register windows, be sure to choose a global
-register that is not affected magically by the function call mechanism.
+@smallexample
+x ? : y
+@end smallexample
-@subsubheading Using the variable
+@noindent
+has the value of @code{x} if that is nonzero; otherwise, the value of
+@code{y}.
-@cindex @code{qsort}, and global register variables
-When calling routines that are not aware of the reservation, be
-cautious if those routines call back into code which uses them. As an
-example, if you call the system library version of @code{qsort}, it may
-clobber your registers during execution, but (if you have selected
-appropriate registers) it will restore them before returning. However
-it will @emph{not} restore them before calling @code{qsort}'s comparison
-function. As a result, global values will not reliably be available to
-the comparison function unless the @code{qsort} function itself is rebuilt.
+This example is perfectly equivalent to
-Similarly, it is not safe to access the global register variables from signal
-handlers or from more than one thread of control. Unless you recompile
-them specially for the task at hand, the system library routines may
-temporarily use the register for other things. Furthermore, since the register
-is not reserved exclusively for the variable, accessing it from handlers of
-asynchronous signals may observe unrelated temporary values residing in the
-register.
+@smallexample
+x ? x : y
+@end smallexample
-@cindex register variable after @code{longjmp}
-@cindex global register after @code{longjmp}
-@cindex value after @code{longjmp}
-@findex longjmp
-@findex setjmp
-On most machines, @code{longjmp} restores to each global register
-variable the value it had at the time of the @code{setjmp}. On some
-machines, however, @code{longjmp} does not change the value of global
-register variables. To be portable, the function that called @code{setjmp}
-should make other arrangements to save the values of the global register
-variables, and to restore them in a @code{longjmp}. This way, the same
-thing happens regardless of what @code{longjmp} does.
+@cindex side effect in @code{?:}
+@cindex @code{?:} side effect
+@noindent
+In this simple case, the ability to omit the middle operand is not
+especially useful. When it becomes useful is when the first operand does,
+or may (if it is a macro argument), contain a side effect. Then repeating
+the operand in the middle would perform the side effect twice. Omitting
+the middle operand uses the value already computed without the undesirable
+effects of recomputing it.
-@node Local Register Variables
-@subsubsection Specifying Registers for Local Variables
-@anchor{Local Reg Vars}
-@cindex local variables, specifying registers
-@cindex specifying registers for local variables
-@cindex registers for local variables
+@node Case Ranges
+@subsection Case Ranges
+@cindex case ranges
+@cindex ranges in case statements
-You can define a local register variable and associate it with a specified
-register like this:
+You can specify a range of consecutive values in a single @code{case} label,
+like this:
@smallexample
-register int *foo asm ("r12");
+case @var{low} ... @var{high}:
@end smallexample
@noindent
-Here @code{r12} is the name of the register that should be used. Note
-that this is the same syntax used for defining global register variables,
-but for a local variable the declaration appears within a function. The
-@code{register} keyword is required, and cannot be combined with
-@code{static}. The register name must be a valid register name for the
-target platform.
+This has the same effect as the proper number of individual @code{case}
+labels, one for each integer value from @var{low} to @var{high}, inclusive.
-Do not use type qualifiers such as @code{const} and @code{volatile}, as
-the outcome may be contrary to expectations. In particular, when the
-@code{const} qualifier is used, the compiler may substitute the
-variable with its initializer in @code{asm} statements, which may cause
-the corresponding operand to appear in a different register.
+This feature is especially useful for ranges of ASCII character codes:
-As with global register variables, it is recommended that you choose
-a register that is normally saved and restored by function calls on your
-machine, so that calls to library routines will not clobber it.
+@smallexample
+case 'A' ... 'Z':
+@end smallexample
-The only supported use for this feature is to specify registers
-for input and output operands when calling Extended @code{asm}
-(@pxref{Extended Asm}). This may be necessary if the constraints for a
-particular machine don't provide sufficient control to select the desired
-register. To force an operand into a register, create a local variable
-and specify the register name after the variable's declaration. Then use
-the local variable for the @code{asm} operand and specify any constraint
-letter that matches the register:
+@strong{Be careful:} Write spaces around the @code{...}, for otherwise
+it may be parsed wrong when you use it with integer values. For example,
+write this:
@smallexample
-register int *p1 asm ("r0") = @dots{};
-register int *p2 asm ("r1") = @dots{};
-register int *result asm ("r0");
-asm ("sysint" : "=r" (result) : "0" (p1), "r" (p2));
+case 1 ... 5:
@end smallexample
-@emph{Warning:} In the above example, be aware that a register (for example
-@code{r0}) can be call-clobbered by subsequent code, including function
-calls and library calls for arithmetic operators on other variables (for
-example the initialization of @code{p2}). In this case, use temporary
-variables for expressions between the register assignments:
+@noindent
+rather than this:
@smallexample
-int t1 = @dots{};
-register int *p1 asm ("r0") = @dots{};
-register int *p2 asm ("r1") = t1;
-register int *result asm ("r0");
-asm ("sysint" : "=r" (result) : "0" (p1), "r" (p2));
+case 1...5:
@end smallexample
-Defining a register variable does not reserve the register. Other than
-when invoking the Extended @code{asm}, the contents of the specified
-register are not guaranteed. For this reason, the following uses
-are explicitly @emph{not} supported. If they appear to work, it is only
-happenstance, and may stop working as intended due to (seemingly)
-unrelated changes in surrounding code, or even minor changes in the
-optimization of a future version of gcc:
+@node Mixed Labels and Declarations
+@subsection Mixed Declarations, Labels and Code
+@cindex mixed declarations and code
+@cindex declarations, mixed with code
+@cindex code, mixed with declarations
-@itemize @bullet
-@item Passing parameters to or from Basic @code{asm}
-@item Passing parameters to or from Extended @code{asm} without using input
-or output operands.
-@item Passing parameters to or from routines written in assembler (or
-other languages) using non-standard calling conventions.
-@end itemize
+ISO C99 and ISO C++ allow declarations and code to be freely mixed
+within compound statements. ISO C23 allows labels to be
+placed before declarations and at the end of a compound statement.
+As an extension, GNU C also allows all this in C90 mode. For example,
+you could do:
-Some developers use Local Register Variables in an attempt to improve
-gcc's allocation of registers, especially in large functions. In this
-case the register name is essentially a hint to the register allocator.
-While in some instances this can generate better code, improvements are
-subject to the whims of the allocator/optimizers. Since there are no
-guarantees that your improvements won't be lost, this usage of Local
-Register Variables is discouraged.
+@smallexample
+int i;
+/* @r{@dots{}} */
+i++;
+int j = i + 2;
+@end smallexample
+
+Each identifier is visible from where it is declared until the end of
+the enclosing block.
+
+@node C++ Comments
+@subsection C++ Style Comments
+@cindex @code{//}
+@cindex C++ comments
+@cindex comments, C++ style
+
+In GNU C, you may use C++ style comments, which start with @samp{//} and
+continue until the end of the line. Many other C implementations allow
+such comments, and they are included in the 1999 C standard. However,
+C++ style comments are not recognized if you specify an @option{-std}
+option specifying a version of ISO C before C99, or @option{-ansi}
+(equivalent to @option{-std=c90}).
+
+@node Escaped Newlines
+@subsection Slightly Looser Rules for Escaped Newlines
+@cindex escaped newlines
+@cindex newlines (escaped)
+
+The preprocessor treatment of escaped newlines is more relaxed
+than that specified by the C90 standard, which requires the newline
+to immediately follow a backslash.
+GCC's implementation allows whitespace in the form
+of spaces, horizontal and vertical tabs, and form feeds between the
+backslash and the subsequent newline. The preprocessor issues a
+warning, but treats it as a valid escaped newline and combines the two
+lines to form a single logical line. This works within comments and
+tokens, as well as between tokens. Comments are @emph{not} treated as
+whitespace for the purposes of this relaxation, since they have not
+yet been replaced with spaces.
+
+@node Hex Floats
+@subsection Hex Floats
+@cindex hex floats
+
+ISO C99 and ISO C++17 support floating-point numbers written not only in
+the usual decimal notation, such as @code{1.55e1}, but also numbers such as
+@code{0x1.fp3} written in hexadecimal format. As a GNU extension, GCC
+supports this in C90 mode (except in some cases when strictly
+conforming) and in C++98, C++11 and C++14 modes. In that format the
+@samp{0x} hex introducer and the @samp{p} or @samp{P} exponent field are
+mandatory. The exponent is a decimal number that indicates the power of
+2 by which the significant part is multiplied. Thus @samp{0x1.f} is
+@tex
+$1 {15\over16}$,
+@end tex
+@ifnottex
+1 15/16,
+@end ifnottex
+@samp{p3} multiplies it by 8, and the value of @code{0x1.fp3}
+is the same as @code{1.55e1}.
+
+Unlike for floating-point numbers in the decimal notation the exponent
+is always required in the hexadecimal notation. Otherwise the compiler
+would not be able to resolve the ambiguity of, e.g., @code{0x1.f}. This
+could mean @code{1.0f} or @code{1.9375} since @samp{f} is also the
+extension for floating-point constants of type @code{float}.
+
+@node Binary constants
+@subsection Binary Constants using the @samp{0b} Prefix
+@cindex Binary constants using the @samp{0b} prefix
+
+Integer constants can be written as binary constants, consisting of a
+sequence of @samp{0} and @samp{1} digits, prefixed by @samp{0b} or
+@samp{0B}. This is particularly useful in environments that operate a
+lot on the bit level (like microcontrollers).
+
+The following statements are identical:
+
+@smallexample
+i = 42;
+i = 0x2a;
+i = 052;
+i = 0b101010;
+@end smallexample
-On the MIPS platform, there is related use for local register variables
-with slightly different characteristics (@pxref{MIPS Coprocessors,,
-Defining coprocessor specifics for MIPS targets, gccint,
-GNU Compiler Collection (GCC) Internals}).
+The type of these constants follows the same rules as for octal or
+hexadecimal integer constants, so suffixes like @samp{L} or @samp{UL}
+can be applied.
-@node Size of an asm
-@subsection Size of an @code{asm}
+@node Dollar Signs
+@subsection Dollar Signs in Identifier Names
+@cindex $
+@cindex dollar signs in identifier names
+@cindex identifier names, dollar signs in
-Some targets require that GCC track the size of each instruction used
-in order to generate correct code. Because the final length of the
-code produced by an @code{asm} statement is only known by the
-assembler, GCC must make an estimate as to how big it will be. It
-does this by counting the number of instructions in the pattern of the
-@code{asm} and multiplying that by the length of the longest
-instruction supported by that processor. (When working out the number
-of instructions, it assumes that any occurrence of a newline or of
-whatever statement separator character is supported by the assembler ---
-typically @samp{;} --- indicates the end of an instruction.)
+In GNU C, you may normally use dollar signs in identifier names.
+This is because many traditional C implementations allow such identifiers.
+However, dollar signs in identifiers are not supported on a few target
+machines, typically because the target assembler does not allow them.
-Normally, GCC's estimate is adequate to ensure that correct
-code is generated, but it is possible to confuse the compiler if you use
-pseudo instructions or assembler macros that expand into multiple real
-instructions, or if you use assembler directives that expand to more
-space in the object file than is needed for a single instruction.
-If this happens then the assembler may produce a diagnostic saying that
-a label is unreachable.
+@node Character Escapes
+@subsection The Character @key{ESC} in Constants
-@cindex @code{asm inline}
-This size is also used for inlining decisions. If you use @code{asm inline}
-instead of just @code{asm}, then for inlining purposes the size of the asm
-is taken as the minimum size, ignoring how many instructions GCC thinks it is.
+You can use the sequence @samp{\e} in a string or character constant to
+stand for the ASCII character @key{ESC}.
@node Alternate Keywords
-@section Alternate Keywords
+@subsection Alternate Keywords
@cindex alternate keywords
@cindex keywords, alternate
@code{__extension__} has no effect aside from this.
-@node Incomplete Enums
-@section Incomplete @code{enum} Types
-
-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 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.
-
-This extension is not supported by GNU C++.
-
@node Function Names
-@section Function Names as Strings
+@subsection Function Names as Strings
@cindex @code{__func__} identifier
@cindex @code{__FUNCTION__} identifier
@cindex @code{__PRETTY_FUNCTION__} identifier
be used to initialize @code{char} arrays or be concatenated with string
literals.
+@node Semantic Extensions
+@section Extensions to C Semantics
+
+GNU C defines useful behavior for some constructs that are not allowed or
+well-defined in standard C.
+
+@menu
+* Function Prototypes:: Prototype declarations and old-style definitions.
+* Pointer Arith:: Arithmetic on @code{void}-pointers and function pointers.
+* Variadic Pointer Args:: Pointer arguments to variadic functions.
+* Pointers to Arrays:: Pointers to arrays with qualifiers work as expected.
+* Const and Volatile Functions:: GCC interprets these specially in C.
+@end menu
+
+@node Function Prototypes
+@subsection Prototypes and Old-Style Function Definitions
+@cindex function prototype declarations
+@cindex old-style function definitions
+@cindex promotion of formal parameters
+
+GNU C extends ISO C to allow a function prototype to override a later
+old-style non-prototype definition. Consider the following example:
+
+@smallexample
+/* @r{Use prototypes unless the compiler is old-fashioned.} */
+#ifdef __STDC__
+#define P(x) x
+#else
+#define P(x) ()
+#endif
+
+/* @r{Prototype function declaration.} */
+int isroot P((uid_t));
+
+/* @r{Old-style function definition.} */
+int
+isroot (x) /* @r{??? lossage here ???} */
+ uid_t x;
+@{
+ return x == 0;
+@}
+@end smallexample
+
+Suppose the type @code{uid_t} happens to be @code{short}. ISO C does
+not allow this example, because subword arguments in old-style
+non-prototype definitions are promoted. Therefore in this example the
+function definition's argument is really an @code{int}, which does not
+match the prototype argument type of @code{short}.
+
+This restriction of ISO C makes it hard to write code that is portable
+to traditional C compilers, because the programmer does not know
+whether the @code{uid_t} type is @code{short}, @code{int}, or
+@code{long}. Therefore, in cases like these GNU C allows a prototype
+to override a later old-style definition. More precisely, in GNU C, a
+function prototype argument type overrides the argument type specified
+by a later old-style definition if the former type is the same as the
+latter type before promotion. Thus in GNU C the above example is
+equivalent to the following:
+
+@smallexample
+int isroot (uid_t);
+
+int
+isroot (uid_t x)
+@{
+ return x == 0;
+@}
+@end smallexample
+
+@noindent
+GNU C++ does not support old-style function definitions, so this
+extension is irrelevant.
+
+@node Pointer Arith
+@subsection Arithmetic on @code{void}- and Function-Pointers
+@cindex void pointers, arithmetic
+@cindex void, size of pointer to
+@cindex function pointers, arithmetic
+@cindex function, size of pointer to
+
+In GNU C, addition and subtraction operations are supported on pointers to
+@code{void} and on pointers to functions. This is done by treating the
+size of a @code{void} or of a function as 1.
+
+A consequence of this is that @code{sizeof} is also allowed on @code{void}
+and on function types, and returns 1.
+
+@opindex Wpointer-arith
+The option @option{-Wpointer-arith} requests a warning if these extensions
+are used.
+
+@node Variadic Pointer Args
+@subsection Pointer Arguments in Variadic Functions
+@cindex pointer arguments in variadic functions
+@cindex variadic functions, pointer arguments
+
+Standard C requires that pointer types used with @code{va_arg} in
+functions with variable argument lists either must be compatible with
+that of the actual argument, or that one type must be a pointer to
+@code{void} and the other a pointer to a character type. GNU C
+implements the POSIX XSI extension that additionally permits the use
+of @code{va_arg} with a pointer type to receive arguments of any other
+pointer type.
+
+In particular, in GNU C @samp{va_arg (ap, void *)} can safely be used
+to consume an argument of any pointer type.
+
+@node Pointers to Arrays
+@subsection Pointers to Arrays with Qualifiers Work as Expected
+@cindex pointers to arrays
+@cindex const qualifier
+
+In GNU C, pointers to arrays with qualifiers work similar to pointers
+to other qualified types. For example, a value of type @code{int (*)[5]}
+can be used to initialize a variable of type @code{const int (*)[5]}.
+These types are incompatible in ISO C because the @code{const} qualifier
+is formally attached to the element type of the array and not the
+array itself.
+
+@smallexample
+extern void
+transpose (int N, int M, double out[M][N], const double in[N][M]);
+double x[3][2];
+double y[2][3];
+@r{@dots{}}
+transpose(3, 2, y, x);
+@end smallexample
+
+@node Const and Volatile Functions
+@subsection Const and Volatile Functions
+@cindex @code{const} applied to function
+@cindex @code{volatile} applied to function
+
+The C standard explicitly leaves the behavior of the @code{const} and
+@code{volatile} type qualifiers applied to functions undefined; these
+constructs can only arise through the use of @code{typedef}. As an extension,
+GCC defines this use of the @code{const} qualifier to have the same meaning
+as the GCC @code{const} function attribute, and the @code{volatile} qualifier
+to be equivalent to the @code{noreturn} attribute.
+@xref{Common Function Attributes}, for more information.
+
+As examples of this usage,
+
+@smallexample
+
+/* @r{Equivalent to:}
+ void fatal () __attribute__ ((noreturn)); */
+typedef void voidfn ();
+volatile voidfn fatal;
+
+/* @r{Equivalent to:}
+ extern int square (int) __attribute__ ((const)); */
+typedef int intfn (int);
+extern const intfn square;
+@end smallexample
+
+In general, using function attributes instead is preferred, since the
+attributes make both the intent of the code and its reliance on a GNU
+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 Return Address
@section Getting the Return or Frame Address of a Function
@c but GCC does not accept it for unions of vector types (PR 88955).
@end smallexample
-@node Offsetof
-@section Support for @code{offsetof}
-@findex __builtin_offsetof
-
-GCC implements for both C and C++ a syntactic extension to implement
-the @code{offsetof} macro.
-
-@smallexample
-primary:
- "__builtin_offsetof" "(" @code{typename} "," offsetof_member_designator ")"
-
-offsetof_member_designator:
- @code{identifier}
- | offsetof_member_designator "." @code{identifier}
- | offsetof_member_designator "[" @code{expr} "]"
-@end smallexample
-
-This extension is sufficient such that
-
-@smallexample
-#define offsetof(@var{type}, @var{member}) __builtin_offsetof (@var{type}, @var{member})
-@end smallexample
-
-@noindent
-is a suitable definition of the @code{offsetof} macro. In C++, @var{type}
-may be dependent. In either case, @var{member} may consist of a single
-identifier, or a sequence of member accesses and array references.
-
@node __sync Builtins
@section Legacy @code{__sync} Built-in Functions for Atomic Memory Access
@end quotation
@end itemize
-@node Binary constants
-@section Binary Constants using the @samp{0b} Prefix
-@cindex Binary constants using the @samp{0b} prefix
-
-Integer constants can be written as binary constants, consisting of a
-sequence of @samp{0} and @samp{1} digits, prefixed by @samp{0b} or
-@samp{0B}. This is particularly useful in environments that operate a
-lot on the bit level (like microcontrollers).
-
-The following statements are identical:
-
-@smallexample
-i = 42;
-i = 0x2a;
-i = 052;
-i = 0b101010;
-@end smallexample
-
-The type of these constants follows the same rules as for octal or
-hexadecimal integer constants, so suffixes like @samp{L} or @samp{UL}
-can be applied.
-
@node OpenMP
@section OpenMP
@cindex OpenMP extension support
projects / thirdparty / gcc.git / commitdiff
