diff options
| author | alk3pInjection <webmaster@raspii.tech> | 2024-02-04 16:16:35 +0800 |
|---|---|---|
| committer | alk3pInjection <webmaster@raspii.tech> | 2024-02-04 16:16:35 +0800 |
| commit | abdaadbcae30fe0c9a66c7516798279fdfd97750 (patch) | |
| tree | 00a54a6e25601e43876d03c1a4a12a749d4a914c /share/doc/gcc/Common-Function-Attributes.html | |
https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads
Change-Id: I7303388733328cd98ab9aa3c30236db67f2e9e9c
Diffstat (limited to 'share/doc/gcc/Common-Function-Attributes.html')
| -rw-r--r-- | share/doc/gcc/Common-Function-Attributes.html | 1982 |
1 files changed, 1982 insertions, 0 deletions
diff --git a/share/doc/gcc/Common-Function-Attributes.html b/share/doc/gcc/Common-Function-Attributes.html new file mode 100644 index 0000000..bde04e7 --- /dev/null +++ b/share/doc/gcc/Common-Function-Attributes.html @@ -0,0 +1,1982 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- This file documents the use of the GNU compilers. + +Copyright (C) 1988-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being "Funding Free Software", the Front-Cover +Texts being (a) (see below), and with the Back-Cover Texts being (b) +(see below). A copy of the license is included in the section entitled +"GNU Free Documentation License". + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>Using the GNU Compiler Collection (GCC): Common Function Attributes</title> + +<meta name="description" content="Using the GNU Compiler Collection (GCC): Common Function Attributes"> +<meta name="keywords" content="Using the GNU Compiler Collection (GCC): Common Function Attributes"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Indices.html#Indices" rel="index" title="Indices"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="Function-Attributes.html#Function-Attributes" rel="up" title="Function Attributes"> +<link href="AArch64-Function-Attributes.html#AArch64-Function-Attributes" rel="next" title="AArch64 Function Attributes"> +<link href="Function-Attributes.html#Function-Attributes" rel="previous" title="Function Attributes"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en_US" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Common-Function-Attributes"></a> +<div class="header"> +<p> +Next: <a href="AArch64-Function-Attributes.html#AArch64-Function-Attributes" accesskey="n" rel="next">AArch64 Function Attributes</a>, Up: <a href="Function-Attributes.html#Function-Attributes" accesskey="u" rel="up">Function Attributes</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Indices.html#Indices" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Common-Function-Attributes-1"></a> +<h4 class="subsection">6.33.1 Common Function Attributes</h4> + +<p>The following attributes are supported on most targets. +</p> +<dl compact="compact"> +<dt><code>access (<var>access-mode</var>, <var>ref-index</var>)</code></dt> +<dt><code>access (<var>access-mode</var>, <var>ref-index</var>, <var>size-index</var>)</code></dt> +<dd> +<p>The <code>access</code> 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 <samp>-Wstringop-overflow</samp>, +<samp>-Wuninitialized</samp>, <samp>-Wunused</samp>, and others. +</p> +<p>The <code>access</code> attribute specifies that a function to whose by-reference +arguments the attribute applies accesses the referenced object according to +<var>access-mode</var>. The <var>access-mode</var> argument is required and must be +one of four names: <code>read_only</code>, <code>read_write</code>, <code>write_only</code>, +or <code>none</code>. The remaining two are positional arguments. +</p> +<p>The required <var>ref-index</var> 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</code> attribute. +</p> +<p>The optional <var>size-index</var> 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</var>, +or the number of bytes when the pointer type is <code>void*</code>. When no +<var>size-index</var> 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. +</p> +<p>The <code>read_only</code> 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</var> +is zero, the referenced object must be initialized. The mode implies +a stronger guarantee than the <code>const</code> 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</code> access mode is the argument to +the <code>puts</code> function, or the second and third arguments to +the <code>memcpy</code> function. +</p> +<div class="smallexample"> +<pre class="smallexample">__attribute__ ((access (read_only, 1))) +int puts (const char*); + +__attribute__ ((access (read_only, 2, 3))) +void* memcpy (void*, const void*, size_t); +</pre></div> + +<p>The <code>read_write</code> access mode applies to arguments of pointer types +without the <code>const</code> 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</var> +is zero, the object referenced by the pointer must be initialized. An example +of the use of the <code>read_write</code> access mode is the first argument to +the <code>strcat</code> function. +</p> +<div class="smallexample"> +<pre class="smallexample">__attribute__ ((access (read_write, 1), access (read_only, 2))) +char* strcat (char*, const char*); +</pre></div> + +<p>The <code>write_only</code> access mode applies to arguments of pointer types +without the <code>const</code> 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</code> access mode is the first argument to +the <code>strcpy</code> function, or the first two arguments to the <code>fgets</code> +function. +</p> +<div class="smallexample"> +<pre class="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*); +</pre></div> + +<p>The access mode <code>none</code> 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</var> argument. When the optional <var>size-index</var> +argument is omitted for an argument of <code>void*</code> 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</code>. +See <a href="Object-Size-Checking.html#Object-Size-Checking">Object Size Checking</a>. +</p> +<p>Note that the <code>access</code> attribute merely specifies how an object +referenced by the pointer argument can be accessed; it does not imply that +an access <strong>will</strong> happen. Also, the <code>access</code> attribute does not +imply the attribute <code>nonnull</code>; 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</code> attribute for more information and +caveats. +</p> +<a name="index-alias-function-attribute"></a> +</dd> +<dt><code>alias ("<var>target</var>")</code></dt> +<dd><p>The <code>alias</code> 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: +</p> +<div class="smallexample"> +<pre class="smallexample">void __f () { /* <span class="roman">Do something.</span> */; } +void f () __attribute__ ((weak, alias ("__f"))); +</pre></div> + +<p>define ‘<samp>f</samp>’ to be a weak alias for ‘<samp>__f</samp>’. In C++, the mangled name +for the target must be used. It is an error if ‘<samp>__f</samp>’ is not defined in +the same translation unit. +</p> +<p>This attribute requires assembler and object file support, +and may not be available on all targets. +</p> +<a name="index-aligned-function-attribute"></a> +</dd> +<dt><code>aligned</code></dt> +<dt><code>aligned (<var>alignment</var>)</code></dt> +<dd><p>The <code>aligned</code> attribute specifies a minimum alignment for +the first instruction of the function, measured in bytes. When specified, +<var>alignment</var> must be an integer constant power of 2. Specifying no +<var>alignment</var> argument implies the ideal alignment for the target. +The <code>__alignof__</code> operator can be used to determine what that is +(see <a href="Alignment.html#Alignment">Alignment</a>). The attribute has no effect when a definition for +the function is not provided in the same translation unit. +</p> +<p>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 <samp>-falign-functions</samp> +(see <a href="Optimize-Options.html#Optimize-Options">Optimize Options</a>) option for this function. +</p> +<p>Note that the effectiveness of <code>aligned</code> 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. +</p> +<p>The <code>aligned</code> attribute can also be used for variables and fields +(see <a href="Variable-Attributes.html#Variable-Attributes">Variable Attributes</a>.) +</p> +<a name="index-alloc_005falign-function-attribute"></a> +</dd> +<dt><code>alloc_align (<var>position</var>)</code></dt> +<dd><p>The <code>alloc_align</code> 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</var>. Meaningful alignments are +powers of 2 greater than one. GCC uses this information to improve +pointer alignment analysis. +</p> +<p>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. +</p> +<p>For instance, +</p> +<div class="smallexample"> +<pre class="smallexample">void* my_memalign (size_t, size_t) __attribute__ ((alloc_align (1))); +</pre></div> + +<p>declares that <code>my_memalign</code> returns memory with minimum alignment +given by parameter 1. +</p> +<a name="index-alloc_005fsize-function-attribute"></a> +</dd> +<dt><code>alloc_size (<var>position</var>)</code></dt> +<dt><code>alloc_size (<var>position-1</var>, <var>position-2</var>)</code></dt> +<dd><p>The <code>alloc_size</code> 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</var>, or by the product +of the arguments at <var>position-1</var> and <var>position-2</var>. Meaningful +sizes are positive values less than <code>PTRDIFF_MAX</code>. GCC uses this +information to improve the results of <code>__builtin_object_size</code>. +</p> +<p>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. +</p> +<p>For instance, +</p> +<div class="smallexample"> +<pre class="smallexample">void* my_calloc (size_t, size_t) __attribute__ ((alloc_size (1, 2))); +void* my_realloc (void*, size_t) __attribute__ ((alloc_size (2))); +</pre></div> + +<p>declares that <code>my_calloc</code> returns memory of the size given by +the product of parameter 1 and 2 and that <code>my_realloc</code> returns memory +of the size given by parameter 2. +</p> +<a name="index-always_005finline-function-attribute"></a> +</dd> +<dt><code>always_inline</code></dt> +<dd><p>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. +</p> +<a name="index-artificial-function-attribute"></a> +</dd> +<dt><code>artificial</code></dt> +<dd><p>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. +</p> +<a name="index-assume_005faligned-function-attribute"></a> +</dd> +<dt><code>assume_aligned (<var>alignment</var>)</code></dt> +<dt><code>assume_aligned (<var>alignment</var>, <var>offset</var>)</code></dt> +<dd><p>The <code>assume_aligned</code> 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</var>. If the attribute has two +arguments, the second argument is misalignment <var>offset</var>. Meaningful +values of <var>alignment</var> are powers of 2 greater than one. Meaningful +values of <var>offset</var> are greater than zero and less than <var>alignment</var>. +</p> +<p>For instance +</p> +<div class="smallexample"> +<pre class="smallexample">void* my_alloc1 (size_t) __attribute__((assume_aligned (16))); +void* my_alloc2 (size_t) __attribute__((assume_aligned (32, 8))); +</pre></div> + +<p>declares that <code>my_alloc1</code> returns 16-byte aligned pointers and +that <code>my_alloc2</code> returns a pointer whose value modulo 32 is equal +to 8. +</p> +<a name="index-cold-function-attribute"></a> +</dd> +<dt><code>cold</code></dt> +<dd><p>The <code>cold</code> 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</code>, as cold to improve optimization +of hot functions that do call marked functions in rare occasions. +</p> +<p>When profile feedback is available, via <samp>-fprofile-use</samp>, cold functions +are automatically detected and this attribute is ignored. +</p> +<a name="index-const-function-attribute"></a> +<a name="index-functions-that-have-no-side-effects"></a> +</dd> +<dt><code>const</code></dt> +<dd><p>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</code> attribute allows GCC to avoid emitting +some calls in repeated invocations of the function with the same argument +values. +</p> +<p>For example, +</p> +<div class="smallexample"> +<pre class="smallexample">int square (int) __attribute__ ((const)); +</pre></div> + +<p>tells GCC that subsequent calls to function <code>square</code> with the same +argument value can be replaced by the result of the first call regardless +of the statements in between. +</p> +<p>The <code>const</code> 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. +</p> +<p>The <code>const</code> attribute imposes greater restrictions on a function’s +definition than the similar <code>pure</code> attribute. Declaring the same +function with both the <code>const</code> and the <code>pure</code> attribute is +diagnosed. Because a const function cannot have any observable side +effects it does not make sense for it to return <code>void</code>. Declaring +such a function is diagnosed. +</p> +<a name="index-pointer-arguments"></a> +<p>Note that a function that has pointer arguments and examines the data +pointed to must <em>not</em> be declared <code>const</code> 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. +</p> +<a name="index-constructor-function-attribute"></a> +<a name="index-destructor-function-attribute"></a> +</dd> +<dt><code>constructor</code></dt> +<dt><code>destructor</code></dt> +<dt><code>constructor (<var>priority</var>)</code></dt> +<dt><code>destructor (<var>priority</var>)</code></dt> +<dd><p>The <code>constructor</code> attribute causes the function to be called +automatically before execution enters <code>main ()</code>. Similarly, the +<code>destructor</code> attribute causes the function to be called +automatically after <code>main ()</code> completes or <code>exit ()</code> is +called. Functions with these attributes are useful for +initializing data that is used implicitly during the execution of +the program. +</p> +<p>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 (see <a href="C_002b_002b-Attributes.html#C_002b_002b-Attributes">C++ Attributes</a>). +However, at present, the order in which constructors for C++ objects +with static storage duration and functions decorated with attribute +<code>constructor</code> are invoked is unspecified. In mixed declarations, +attribute <code>init_priority</code> can be used to impose a specific ordering. +</p> +<p>Using the argument forms of the <code>constructor</code> and <code>destructor</code> +attributes on targets where the feature is not supported is rejected with +an error. +</p> +<a name="index-copy-function-attribute"></a> +</dd> +<dt><code>copy</code></dt> +<dt><code>copy (<var>function</var>)</code></dt> +<dd><p>The <code>copy</code> attribute applies the set of attributes with which +<var>function</var> 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</code> +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</code> attribute copies only syntactic and semantic attributes +but not attributes that affect a symbol’s linkage or visibility such as +<code>alias</code>, <code>visibility</code>, or <code>weak</code>. The <code>deprecated</code> +and <code>target_clones</code> attribute are also not copied. +See <a href="Common-Type-Attributes.html#Common-Type-Attributes">Common Type Attributes</a>. +See <a href="Common-Variable-Attributes.html#Common-Variable-Attributes">Common Variable Attributes</a>. +</p> +<p>For example, the <var>StrongAlias</var> macro below makes use of the <code>alias</code> +and <code>copy</code> attributes to define an alias named <var>alloc</var> for function +<var>allocate</var> declared with attributes <var>alloc_size</var>, <var>malloc</var>, and +<var>nothrow</var>. Thanks to the <code>__typeof__</code> operator the alias has +the same type as the target function. As a result of the <code>copy</code> +attribute the alias also shares the same attributes as the target. +</p> +<div class="smallexample"> +<pre class="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); +</pre></div> + +<a name="index-deprecated-function-attribute"></a> +</dd> +<dt><code>deprecated</code></dt> +<dt><code>deprecated (<var>msg</var>)</code></dt> +<dd><p>The <code>deprecated</code> 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: +</p> +<div class="smallexample"> +<pre class="smallexample">int old_fn () __attribute__ ((deprecated)); +int old_fn (); +int (*fn_ptr)() = old_fn; +</pre></div> + +<p>results in a warning on line 3 but not line 2. The optional <var>msg</var> +argument, which must be a string, is printed in the warning if +present. +</p> +<p>The <code>deprecated</code> attribute can also be used for variables and +types (see <a href="Variable-Attributes.html#Variable-Attributes">Variable Attributes</a>, see <a href="Type-Attributes.html#Type-Attributes">Type Attributes</a>.) +</p> +<p>The message attached to the attribute is affected by the setting of +the <samp>-fmessage-length</samp> option. +</p> +<a name="index-unavailable-function-attribute"></a> +</dd> +<dt><code>unavailable</code></dt> +<dt><code>unavailable (<var>msg</var>)</code></dt> +<dd><p>The <code>unavailable</code> 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</code> attribute behaves in the same manner as +<code>deprecated</code>. +</p> +<p>The <code>unavailable</code> attribute can also be used for variables and +types (see <a href="Variable-Attributes.html#Variable-Attributes">Variable Attributes</a>, see <a href="Type-Attributes.html#Type-Attributes">Type Attributes</a>.) +</p> +<a name="index-error-function-attribute"></a> +<a name="index-warning-function-attribute"></a> +</dd> +<dt><code>error ("<var>message</var>")</code></dt> +<dt><code>warning ("<var>message</var>")</code></dt> +<dd><p>If the <code>error</code> or <code>warning</code> 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</var> is diagnosed. +This is useful +for compile-time checking, especially together with <code>__builtin_constant_p</code> +and inline functions where checking the inline function arguments is not +possible through <code>extern char [(condition) ? 1 : -1];</code> tricks. +</p> +<p>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*</code> 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. +</p> +<a name="index-externally_005fvisible-function-attribute"></a> +</dd> +<dt><code>externally_visible</code></dt> +<dd><p>This attribute, attached to a global variable or function, nullifies +the effect of the <samp>-fwhole-program</samp> command-line option, so the +object remains visible outside the current compilation unit. +</p> +<p>If <samp>-fwhole-program</samp> is used together with <samp>-flto</samp> and +<code>gold</code> is used as the linker plugin, +<code>externally_visible</code> attributes are automatically added to functions +(not variable yet due to a current <code>gold</code> issue) +that are accessed outside of LTO objects according to resolution file +produced by <code>gold</code>. +For other linkers that cannot generate resolution file, +explicit <code>externally_visible</code> attributes are still necessary. +</p> +<a name="index-fd_005farg-function-attribute"></a> +</dd> +<dt><code>fd_arg</code></dt> +<dt><code>fd_arg (<var>N</var>)</code></dt> +<dd><p>The <code>fd_arg</code> attribute may be applied to a function that takes an open +file descriptor at referenced argument <var>N</var>. +</p> +<p>It indicates that the passed filedescriptor must not have been closed. +Therefore, when the analyzer is enabled with <samp>-fanalyzer</samp>, the +analyzer may emit a <samp>-Wanalyzer-fd-use-after-close</samp> diagnostic +if it detects a code path in which a function with this attribute is +called with a closed file descriptor. +</p> +<p>The attribute also indicates that the file descriptor must have been checked for +validity before usage. Therefore, analyzer may emit +<samp>-Wanalyzer-fd-use-without-check</samp> 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. +</p> +<a name="index-fd_005farg_005fread-function-attribute"></a> +</dd> +<dt><code>fd_arg_read</code></dt> +<dt><code>fd_arg_read (<var>N</var>)</code></dt> +<dd><p>The <code>fd_arg_read</code> is identical to <code>fd_arg</code>, 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. +</p> +<p>The analyzer may emit a <samp>-Wanalyzer-access-mode-mismatch</samp> +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</code>. +</p> +<a name="index-fd_005farg_005fwrite-function-attribute"></a> +</dd> +<dt><code>fd_arg_write</code></dt> +<dt><code>fd_arg_write (<var>N</var>)</code></dt> +<dd><p>The <code>fd_arg_write</code> is identical to <code>fd_arg_read</code> except that the +analyzer may emit a <samp>-Wanalyzer-access-mode-mismatch</samp> 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</code>. +</p> +<a name="index-flatten-function-attribute"></a> +</dd> +<dt><code>flatten</code></dt> +<dd><p>Generally, inlining into a function is limited. For a function marked with +this attribute, every call inside this function is inlined, if possible. +Functions declared with attribute <code>noinline</code> and similar are not +inlined. Whether the function itself is considered for inlining depends +on its size and the current inlining parameters. +</p> +<a name="index-format-function-attribute"></a> +<a name="index-functions-with-printf_002c-scanf_002c-strftime-or-strfmon-style-arguments"></a> +<a name="index-Wformat-3"></a> +</dd> +<dt><code>format (<var>archetype</var>, <var>string-index</var>, <var>first-to-check</var>)</code></dt> +<dd><p>The <code>format</code> attribute specifies that a function takes <code>printf</code>, +<code>scanf</code>, <code>strftime</code> or <code>strfmon</code> style arguments that +should be type-checked against a format string. For example, the +declaration: +</p> +<div class="smallexample"> +<pre class="smallexample">extern int +my_printf (void *my_object, const char *my_format, ...) + __attribute__ ((format (printf, 2, 3))); +</pre></div> + +<p>causes the compiler to check the arguments in calls to <code>my_printf</code> +for consistency with the <code>printf</code> style format string argument +<code>my_format</code>. +</p> +<p>The parameter <var>archetype</var> determines how the format string is +interpreted, and should be <code>printf</code>, <code>scanf</code>, <code>strftime</code>, +<code>gnu_printf</code>, <code>gnu_scanf</code>, <code>gnu_strftime</code> or +<code>strfmon</code>. (You can also use <code>__printf__</code>, +<code>__scanf__</code>, <code>__strftime__</code> or <code>__strfmon__</code>.) On +MinGW targets, <code>ms_printf</code>, <code>ms_scanf</code>, and +<code>ms_strftime</code> are also present. +<var>archetype</var> values such as <code>printf</code> refer to the formats accepted +by the system’s C runtime library, +while values prefixed with ‘<samp>gnu_</samp>’ always refer +to the formats accepted by the GNU C Library. On Microsoft Windows +targets, values prefixed with ‘<samp>ms_</samp>’ refer to the formats accepted by the +<samp>msvcrt.dll</samp> library. +The parameter <var>string-index</var> +specifies which argument is the format string argument (starting +from 1), while <var>first-to-check</var> 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</code>), specify the third parameter as zero. In this case the +compiler only checks the format string for consistency. For +<code>strftime</code> formats, the third parameter is required to be zero. +Since non-static C++ methods have an implicit <code>this</code> argument, the +arguments of such methods should be counted from two, not one, when +giving values for <var>string-index</var> and <var>first-to-check</var>. +</p> +<p>In the example above, the format string (<code>my_format</code>) is the second +argument of the function <code>my_print</code>, and the arguments to check +start with the third argument, so the correct parameters for the format +attribute are 2 and 3. +</p> +<a name="index-ffreestanding-3"></a> +<a name="index-fno_002dbuiltin-2"></a> +<p>The <code>format</code> 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 +<samp>-ffreestanding</samp> or <samp>-fno-builtin</samp> is used) checks formats +for the standard library functions <code>printf</code>, <code>fprintf</code>, +<code>sprintf</code>, <code>scanf</code>, <code>fscanf</code>, <code>sscanf</code>, <code>strftime</code>, +<code>vprintf</code>, <code>vfprintf</code> and <code>vsprintf</code> whenever such +warnings are requested (using <samp>-Wformat</samp>), so there is no need to +modify the header file <samp>stdio.h</samp>. In C99 mode, the functions +<code>snprintf</code>, <code>vsnprintf</code>, <code>vscanf</code>, <code>vfscanf</code> and +<code>vsscanf</code> are also checked. Except in strictly conforming C +standard modes, the X/Open function <code>strfmon</code> is also checked as +are <code>printf_unlocked</code> and <code>fprintf_unlocked</code>. +See <a href="C-Dialect-Options.html#C-Dialect-Options">Options Controlling C Dialect</a>. +</p> +<p>For Objective-C dialects, <code>NSString</code> (or <code>__NSString__</code>) 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. +</p> +<p>The target may also provide additional types of format checks. +See <a href="Target-Format-Checks.html#Target-Format-Checks">Format Checks Specific to Particular +Target Machines</a>. +</p> +<a name="index-format_005farg-function-attribute"></a> +<a name="index-Wformat_002dnonliteral-1"></a> +</dd> +<dt><code>format_arg (<var>string-index</var>)</code></dt> +<dd><p>The <code>format_arg</code> attribute specifies that a function takes one or +more format strings for a <code>printf</code>, <code>scanf</code>, <code>strftime</code> or +<code>strfmon</code> style function and modifies it (for example, to translate +it into another language), so the result can be passed to a +<code>printf</code>, <code>scanf</code>, <code>strftime</code> or <code>strfmon</code> 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</code> attributes may be applied to the same function, each +designating a distinct parameter as a format string. For example, the +declaration: +</p> +<div class="smallexample"> +<pre class="smallexample">extern char * +my_dgettext (char *my_domain, const char *my_format) + __attribute__ ((format_arg (2))); +</pre></div> + +<p>causes the compiler to check the arguments in calls to a <code>printf</code>, +<code>scanf</code>, <code>strftime</code> or <code>strfmon</code> type function, whose +format string argument is a call to the <code>my_dgettext</code> function, for +consistency with the format string argument <code>my_format</code>. If the +<code>format_arg</code> 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 +<samp>-Wformat-nonliteral</samp> is used, but the calls could not be checked +without the attribute. +</p> +<p>In calls to a function declared with more than one <code>format_arg</code> +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</code> family of functions. +</p> +<p>The parameter <var>string-index</var> specifies which argument is the format +string argument (starting from one). Since non-static C++ methods have +an implicit <code>this</code> argument, the arguments of such methods should +be counted from two. +</p> +<p>The <code>format_arg</code> attribute allows you to identify your own +functions that modify format strings, so that GCC can check the +calls to <code>printf</code>, <code>scanf</code>, <code>strftime</code> or <code>strfmon</code> +type function whose operands are a call to one of your own function. +The compiler always treats <code>gettext</code>, <code>dgettext</code>, and +<code>dcgettext</code> in this manner except when strict ISO C support is +requested by <samp>-ansi</samp> or an appropriate <samp>-std</samp> option, or +<samp>-ffreestanding</samp> or <samp>-fno-builtin</samp> +is used. See <a href="C-Dialect-Options.html#C-Dialect-Options">Options +Controlling C Dialect</a>. +</p> +<p>For Objective-C dialects, the <code>format-arg</code> attribute may refer to an +<code>NSString</code> reference for compatibility with the <code>format</code> attribute +above. +</p> +<p>The target may also allow additional types in <code>format-arg</code> attributes. +See <a href="Target-Format-Checks.html#Target-Format-Checks">Format Checks Specific to Particular +Target Machines</a>. +</p> +<a name="index-gnu_005finline-function-attribute"></a> +</dd> +<dt><code>gnu_inline</code></dt> +<dd><p>This attribute should be used with a function that is also declared +with the <code>inline</code> keyword. It directs GCC to treat the function +as if it were defined in gnu90 mode even when compiling in C99 or +gnu99 mode. +</p> +<p>If the function is declared <code>extern</code>, 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</code>, 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. +</p> +<p>In C, if the function is neither <code>extern</code> nor <code>static</code>, then +the function is compiled as a standalone function, as well as being +inlined where possible. +</p> +<p>This is how GCC traditionally handled functions declared +<code>inline</code>. Since ISO C99 specifies a different semantics for +<code>inline</code>, 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__</code> or +<code>__GNUC_STDC_INLINE__</code> are defined. See <a href="Inline.html#Inline">An Inline +Function is As Fast As a Macro</a>. +</p> +<p>In C++, this attribute does not depend on <code>extern</code> in any way, +but it still requires the <code>inline</code> keyword to enable its special +behavior. +</p> +<a name="index-hot-function-attribute"></a> +</dd> +<dt><code>hot</code></dt> +<dd><p>The <code>hot</code> 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. +</p> +<p>When profile feedback is available, via <samp>-fprofile-use</samp>, hot functions +are automatically detected and this attribute is ignored. +</p> +<a name="index-ifunc-function-attribute"></a> +<a name="index-indirect-functions"></a> +<a name="index-functions-that-are-dynamically-resolved"></a> +</dd> +<dt><code>ifunc ("<var>resolver</var>")</code></dt> +<dd><p>The <code>ifunc</code> 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: +</p> +<div class="smallexample"> +<pre class="smallexample">void *my_memcpy (void *dst, const void *src, size_t len) +{ + … + return dst; +} + +static void * (*resolve_memcpy (void))(void *, const void *, size_t) +{ + return my_memcpy; // we will just always select this routine +} +</pre></div> + +<p>The exported header file declaring the function the user calls would +contain: +</p> +<div class="smallexample"> +<pre class="smallexample">extern void *memcpy (void *, const void *, size_t); +</pre></div> + +<p>allowing the user to call <code>memcpy</code> 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: +</p> +<div class="smallexample"> +<pre class="smallexample">void *memcpy (void *, const void *, size_t) + __attribute__ ((ifunc ("resolve_memcpy"))); +</pre></div> + +<p>In C++, the <code>ifunc</code> 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</code> should be declared to return a pointer to a non-member +function taking pointer to <code>C</code> 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 <samp>-Wattribute-alias</samp> 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 <samp>-Wno-pmf-conversions</samp> option. For example: +</p> +<div class="smallexample"> +<pre class="smallexample">class S +{ +private: + int debug_impl (int); + int optimized_impl (int); + + typedef int Func (S*, int); + + static Func* resolver (); +public: + + int interface (int); +}; + +int S::debug_impl (int) { /* <span class="roman">…</span> */ } +int S::optimized_impl (int) { /* <span class="roman">…</span> */ } + +S::Func* S::resolver () +{ + int (S::*pimpl) (int) + = getenv ("DEBUG") ? &S::debug_impl : &S::optimized_impl; + + // Cast triggers -Wno-pmf-conversions. + return reinterpret_cast<Func*>(pimpl); +} + +int S::interface (int) __attribute__ ((ifunc ("_ZN1S8resolverEv"))); +</pre></div> + +<p>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. +</p> +</dd> +<dt><code>interrupt</code></dt> +<dt><code>interrupt_handler</code></dt> +<dd><p>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. +</p> +<a name="index-leaf-function-attribute"></a> +</dd> +<dt><code>leaf</code></dt> +<dd><p>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</code> 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. +</p> +<p>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</code> function is a leaf function, but +<code>qsort</code> is not. +</p> +<p>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</code> attribute or mark all such static variables +<code>volatile</code>. 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. +</p> +<p>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. +</p> +<a name="index-malloc-function-attribute"></a> +<a name="index-functions-that-behave-like-malloc"></a> +</dd> +<dt><code>malloc</code></dt> +<dt><code>malloc (<var>deallocator</var>)</code></dt> +<dt><code>malloc (<var>deallocator</var>, <var>ptr-index</var>)</code></dt> +<dd><p>Attribute <code>malloc</code> indicates that a function is <code>malloc</code>-like, +i.e., that the pointer <var>P</var> 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</var>. In +addition, GCC predicts that a function with the attribute returns +non-null in most cases. +</p> +<p>Independently, the form of the attribute with one or two arguments +associates <code>deallocator</code> as a suitable deallocation function for +pointers returned from the <code>malloc</code>-like function. <var>ptr-index</var> +denotes the positional argument to which when the pointer is passed in +calls to <code>deallocator</code> has the effect of deallocating it. +</p> +<p>Using the attribute with no arguments is designed to improve optimization +by relying on the aliasing property it implies. Functions like <code>malloc</code> +and <code>calloc</code> have this property because they return a pointer to +uninitialized or zeroed-out, newly obtained storage. However, functions +like <code>realloc</code> 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. +</p> +<p>Associating a function with a <var>deallocator</var> helps detect calls to +mismatched allocation and deallocation functions and diagnose them under +the control of options such as <samp>-Wmismatched-dealloc</samp>. It also +makes it possible to diagnose attempts to deallocate objects that were not +allocated dynamically, by <samp>-Wfree-nonheap-object</samp>. To indicate +that an allocation function both satisifies the nonaliasing property and +has a deallocator associated with it, both the plain form of the attribute +and the one with the <var>deallocator</var> 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</code> is not accepted on inline +functions. For the same reason, using the attribute prevents both +the allocation and deallocation functions from being expanded inline. +</p> +<p>For example, besides stating that the functions return pointers that do +not alias any others, the following declarations make <code>fclose</code> +a suitable deallocator for pointers returned from all functions except +<code>popen</code>, and <code>pclose</code> as the only suitable deallocator for +pointers returned from <code>popen</code>. The deallocator functions must +be declared before they can be referenced in the attribute. +</p> +<div class="smallexample"> +<pre class="smallexample">int fclose (FILE*); +int pclose (FILE*); + +__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); +</pre></div> + +<p>The warnings guarded by <samp>-fanalyzer</samp> respect allocation and +deallocation pairs marked with the <code>malloc</code>. In particular: +</p> +<ul> +<li> The analyzer emits a <samp>-Wanalyzer-mismatching-deallocation</samp> +diagnostic if there is an execution path in which the result of an +allocation call is passed to a different deallocator. + +</li><li> The analyzer emits a <samp>-Wanalyzer-double-free</samp> +diagnostic if there is an execution path in which a value is passed +more than once to a deallocation call. + +</li><li> 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 +<samp>-Wanalyzer-possible-null-dereference</samp> and +<samp>-Wanalyzer-possible-null-argument</samp> diagnostics. +If the allocator always returns non-null, use +<code>__attribute__ ((returns_nonnull))</code> to suppress these warnings. +For example: +<div class="smallexample"> +<pre class="smallexample">char *xstrdup (const char *) + __attribute__((malloc (free), returns_nonnull)); +</pre></div> + +</li><li> The analyzer emits a <samp>-Wanalyzer-use-after-free</samp> +diagnostic if there is an execution path in which the memory passed +by pointer to a deallocation call is used after the deallocation. + +</li><li> The analyzer emits a <samp>-Wanalyzer-malloc-leak</samp> diagnostic if +there is an execution path in which the result of an allocation call +is leaked (without being passed to the deallocation function). + +</li><li> The analyzer emits a <samp>-Wanalyzer-free-of-non-heap</samp> diagnostic +if a deallocation function is used on a global or on-stack variable. + +</li></ul> + +<p>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))</code> so that <samp>-fanalyzer</samp> can emit +a <samp>-Wanalyzer-possible-null-argument</samp> diagnostic for code paths +in which the deallocator is called with null. +</p> +<a name="index-no_005ficf-function-attribute"></a> +</dd> +<dt><code>no_icf</code></dt> +<dd><p>This function attribute prevents a functions from being merged with another +semantically equivalent function. +</p> +<a name="index-no_005finstrument_005ffunction-function-attribute"></a> +<a name="index-finstrument_002dfunctions-1"></a> +<a name="index-p-1"></a> +<a name="index-pg-1"></a> +</dd> +<dt><code>no_instrument_function</code></dt> +<dd><p>If any of <samp>-finstrument-functions</samp>, <samp>-p</samp>, or <samp>-pg</samp> are +given, profiling function calls are +generated at entry and exit of most user-compiled functions. +Functions with this attribute are not so instrumented. +</p> +<a name="index-no_005fprofile_005finstrument_005ffunction-function-attribute"></a> +</dd> +<dt><code>no_profile_instrument_function</code></dt> +<dd><p>The <code>no_profile_instrument_function</code> attribute on functions is used +to inform the compiler that it should not process any profile feedback based +optimization code instrumentation. +</p> +<a name="index-no_005freorder-function-attribute"></a> +</dd> +<dt><code>no_reorder</code></dt> +<dd><p>Do not reorder functions or variables marked <code>no_reorder</code> +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 <samp>-fno-toplevel-reorder</samp> option, but only applies to the +marked symbols. +</p> +<a name="index-no_005fsanitize-function-attribute"></a> +</dd> +<dt><code>no_sanitize ("<var>sanitize_option</var>")</code></dt> +<dd><p>The <code>no_sanitize</code> attribute on functions is used +to inform the compiler that it should not do sanitization of any option +mentioned in <var>sanitize_option</var>. A list of values acceptable by +the <samp>-fsanitize</samp> option can be provided. +</p> +<div class="smallexample"> +<pre class="smallexample">void __attribute__ ((no_sanitize ("alignment", "object-size"))) +f () { /* <span class="roman">Do something.</span> */; } +void __attribute__ ((no_sanitize ("alignment,object-size"))) +g () { /* <span class="roman">Do something.</span> */; } +</pre></div> + +<a name="index-no_005fsanitize_005faddress-function-attribute"></a> +</dd> +<dt><code>no_sanitize_address</code></dt> +<dt><code>no_address_safety_analysis</code></dt> +<dd><p>The <code>no_sanitize_address</code> attribute on functions is used +to inform the compiler that it should not instrument memory accesses +in the function when compiling with the <samp>-fsanitize=address</samp> option. +The <code>no_address_safety_analysis</code> is a deprecated alias of the +<code>no_sanitize_address</code> attribute, new code should use +<code>no_sanitize_address</code>. +</p> +<a name="index-no_005fsanitize_005fthread-function-attribute"></a> +</dd> +<dt><code>no_sanitize_thread</code></dt> +<dd><p>The <code>no_sanitize_thread</code> attribute on functions is used +to inform the compiler that it should not instrument memory accesses +in the function when compiling with the <samp>-fsanitize=thread</samp> option. +</p> +<a name="index-no_005fsanitize_005fundefined-function-attribute"></a> +</dd> +<dt><code>no_sanitize_undefined</code></dt> +<dd><p>The <code>no_sanitize_undefined</code> attribute on functions is used +to inform the compiler that it should not check for undefined behavior +in the function when compiling with the <samp>-fsanitize=undefined</samp> option. +</p> +<a name="index-no_005fsanitize_005fcoverage-function-attribute"></a> +</dd> +<dt><code>no_sanitize_coverage</code></dt> +<dd><p>The <code>no_sanitize_coverage</code> attribute on functions is used +to inform the compiler that it should not do coverage-guided +fuzzing code instrumentation (<samp>-fsanitize-coverage</samp>). +</p> +<a name="index-no_005fsplit_005fstack-function-attribute"></a> +<a name="index-fsplit_002dstack-1"></a> +</dd> +<dt><code>no_split_stack</code></dt> +<dd><p>If <samp>-fsplit-stack</samp> is given, functions have a small +prologue which decides whether to split the stack. Functions with the +<code>no_split_stack</code> attribute do not have that prologue, and thus +may run with only a small amount of stack space available. +</p> +<a name="index-no_005fstack_005flimit-function-attribute"></a> +</dd> +<dt><code>no_stack_limit</code></dt> +<dd><p>This attribute locally overrides the <samp>-fstack-limit-register</samp> +and <samp>-fstack-limit-symbol</samp> command-line options; it has the effect +of disabling stack limit checking in the function it applies to. +</p> +<a name="index-noclone-function-attribute"></a> +</dd> +<dt><code>noclone</code></dt> +<dd><p>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. +</p> +<a name="index-noinline-function-attribute"></a> +</dd> +<dt><code>noinline</code></dt> +<dd><p>This function attribute prevents a function from being considered for +inlining. +If the function does not have side effects, there are optimizations +other than inlining that cause function calls to be optimized away, +although the function call is live. To keep such calls from being +optimized away, put +</p><div class="smallexample"> +<pre class="smallexample">asm (""); +</pre></div> + +<p>(see <a href="Extended-Asm.html#Extended-Asm">Extended Asm</a>) in the called function, to serve as a special +side effect. +</p> +<a name="index-noipa-function-attribute"></a> +</dd> +<dt><code>noipa</code></dt> +<dd><p>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>, <code>noclone</code> and +<code>no_icf</code> 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. This attribute is supported mainly for the purpose +of testing the compiler. +</p> +<a name="index-nonnull-function-attribute"></a> +<a name="index-functions-with-non_002dnull-pointer-arguments"></a> +</dd> +<dt><code>nonnull</code></dt> +<dt><code>nonnull (<var>arg-index</var>, …)</code></dt> +<dd><p>The <code>nonnull</code> 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: +</p> +<div class="smallexample"> +<pre class="smallexample">extern void * +my_memcpy (void *dest, const void *src, size_t len) + __attribute__((nonnull (1, 2))); +</pre></div> + +<p>informs the compiler that, in calls to <code>my_memcpy</code>, arguments +<var>dest</var> and <var>src</var> must be non-null. +</p> +<p>The attribute has an effect both on functions calls and function definitions. +</p> +<p>For function calls: +</p><ul> +<li> If the compiler determines that a null pointer is +passed in an argument slot marked as non-null, and the +<samp>-Wnonnull</samp> option is enabled, a warning is issued. +See <a href="Warning-Options.html#Warning-Options">Warning Options</a>. +</li><li> The <samp>-fisolate-erroneous-paths-attribute</samp> option can be +specified to have GCC transform calls with null arguments to non-null +functions into traps. See <a href="Optimize-Options.html#Optimize-Options">Optimize Options</a>. +</li><li> The compiler may also perform optimizations based on the +knowledge that certain function arguments cannot be null. These +optimizations can be disabled by the +<samp>-fno-delete-null-pointer-checks</samp> option. See <a href="Optimize-Options.html#Optimize-Options">Optimize Options</a>. +</li></ul> + +<p>For function definitions: +</p><ul> +<li> If the compiler determines that a function parameter that is +marked with nonnull is compared with null, and +<samp>-Wnonnull-compare</samp> option is enabled, a warning is issued. +See <a href="Warning-Options.html#Warning-Options">Warning Options</a>. +</li><li> The compiler may also perform optimizations based on the +knowledge that <code>nonnull</code> parameters cannot be null. This can +currently not be disabled other than by removing the nonnull +attribute. +</li></ul> + +<p>If no <var>arg-index</var> is given to the <code>nonnull</code> attribute, +all pointer arguments are marked as non-null. To illustrate, the +following declaration is equivalent to the previous example: +</p> +<div class="smallexample"> +<pre class="smallexample">extern void * +my_memcpy (void *dest, const void *src, size_t len) + __attribute__((nonnull)); +</pre></div> + +<a name="index-noplt-function-attribute"></a> +</dd> +<dt><code>noplt</code></dt> +<dd><p>The <code>noplt</code> attribute is the counterpart to option <samp>-fno-plt</samp>. +Calls to functions marked with this attribute in position-independent code +do not use the PLT. +</p> +<div class="smallexample"> +<pre class="smallexample">/* Externally defined function foo. */ +int foo () __attribute__ ((noplt)); + +int +main (/* <span class="roman">…</span> */) +{ + /* <span class="roman">…</span> */ + foo (); + /* <span class="roman">…</span> */ +} +</pre></div> + +<p>The <code>noplt</code> attribute on function <code>foo</code> +tells the compiler to assume that +the function <code>foo</code> is externally defined and that the call to +<code>foo</code> must avoid the PLT +in position-independent code. +</p> +<p>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. +</p> +<a name="index-noreturn-function-attribute"></a> +<a name="index-functions-that-never-return"></a> +</dd> +<dt><code>noreturn</code></dt> +<dd><p>A few standard library functions, such as <code>abort</code> and <code>exit</code>, +cannot return. GCC knows this automatically. Some programs define +their own functions that never return. You can declare them +<code>noreturn</code> to tell the compiler this fact. For example, +</p> +<div class="smallexample"> +<pre class="smallexample">void fatal () __attribute__ ((noreturn)); + +void +fatal (/* <span class="roman">…</span> */) +{ + /* <span class="roman">…</span> */ /* <span class="roman">Print error message.</span> */ /* <span class="roman">…</span> */ + exit (1); +} +</pre></div> + +<p>The <code>noreturn</code> keyword tells the compiler to assume that +<code>fatal</code> cannot return. It can then optimize without regard to what +would happen if <code>fatal</code> ever did return. This makes slightly +better code. More importantly, it helps avoid spurious warnings of +uninitialized variables. +</p> +<p>The <code>noreturn</code> keyword does not affect the exceptional path when that +applies: a <code>noreturn</code>-marked function may still return to the caller +by throwing an exception or calling <code>longjmp</code>. +</p> +<p>In order to preserve backtraces, GCC will never turn calls to +<code>noreturn</code> functions into tail calls. +</p> +<p>Do not assume that registers saved by the calling function are +restored before calling the <code>noreturn</code> function. +</p> +<p>It does not make sense for a <code>noreturn</code> function to have a return +type other than <code>void</code>. +</p> +<a name="index-nothrow-function-attribute"></a> +</dd> +<dt><code>nothrow</code></dt> +<dd><p>The <code>nothrow</code> 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</code> and <code>bsearch</code> that +take function pointer arguments. +</p> +<a name="index-optimize-function-attribute"></a> +</dd> +<dt><code>optimize (<var>level</var>, …)</code></dt> +<dt><code>optimize (<var>string</var>, …)</code></dt> +<dd><p>The <code>optimize</code> 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. +</p> +<p>Valid arguments are constant non-negative integers and +strings. Each numeric argument specifies an optimization <var>level</var>. +Each <var>string</var> argument consists of one or more comma-separated +substrings. Each substring that begins with the letter <code>O</code> refers +to an optimization option such as <samp>-O0</samp> or <samp>-Os</samp>. Other +substrings are taken as suffixes to the <code>-f</code> prefix jointly +forming the name of an optimization option. See <a href="Optimize-Options.html#Optimize-Options">Optimize Options</a>. +</p> +<p>‘<samp>#pragma GCC optimize</samp>’ can be used to set optimization options +for more than one function. See <a href="Function-Specific-Option-Pragmas.html#Function-Specific-Option-Pragmas">Function Specific Option Pragmas</a>, +for details about the pragma. +</p> +<p>Providing multiple strings as arguments separated by commas to specify +multiple options is equivalent to separating the option suffixes with +a comma (‘<samp>,</samp>’) within a single string. Spaces are not permitted +within the strings. +</p> +<p>Not every optimization option that starts with the <var>-f</var> prefix +specified by the attribute necessarily has an effect on the function. +The <code>optimize</code> attribute should be used for debugging purposes only. +It is not suitable in production code. +</p> +<a name="index-patchable_005ffunction_005fentry-function-attribute"></a> +<a name="index-extra-NOP-instructions-at-the-function-entry-point"></a> +</dd> +<dt><code>patchable_function_entry</code></dt> +<dd><p>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. +</p> +<p>The <code>patchable_function_entry</code> 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 +<samp>-fpatchable-function-entry=N,M</samp>, generating <var>N</var> NOPs, with +the function entry point before the <var>M</var>th NOP instruction. +<var>M</var> defaults to 0 if omitted e.g. function entry point is before +the first NOP. +</p> +<p>If patchable function entries are enabled globally using the command-line +option <samp>-fpatchable-function-entry=N,M</samp>, then you must disable +instrumentation on all functions that are part of the instrumentation +framework with the attribute <code>patchable_function_entry (0)</code> +to prevent recursion. +</p> +<a name="index-pure-function-attribute"></a> +<a name="index-functions-that-have-no-side-effects-1"></a> +</dd> +<dt><code>pure</code></dt> +<dd> +<p>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</code> attribute allows GCC to avoid emitting some calls in repeated +invocations of the function with the same argument values. +</p> +<p>The <code>pure</code> 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</code> +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. +</p> +<p>For example, +</p> +<div class="smallexample"> +<pre class="smallexample">int hash (char *) __attribute__ ((pure)); +</pre></div> + +<p>tells GCC that subsequent calls to the function <code>hash</code> with the same +string can be replaced by the result of the first call provided the state +of the program observable by <code>hash</code>, including the contents of the array +itself, does not change in between. Even though <code>hash</code> 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</code> pointer in C++ +non-static member functions. +</p> +<p>Some common examples of pure functions are <code>strlen</code> or <code>memcmp</code>. +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</code> function in +a multithreading environment). +</p> +<p>The <code>pure</code> attribute imposes similar but looser restrictions on +a function’s definition than the <code>const</code> attribute: <code>pure</code> +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</code> and the <code>const</code> 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</code>. +Declaring such a function is diagnosed. +</p> +<a name="index-returns_005fnonnull-function-attribute"></a> +</dd> +<dt><code>returns_nonnull</code></dt> +<dd><p>The <code>returns_nonnull</code> attribute specifies that the function +return value should be a non-null pointer. For instance, the declaration: +</p> +<div class="smallexample"> +<pre class="smallexample">extern void * +mymalloc (size_t len) __attribute__((returns_nonnull)); +</pre></div> + +<p>lets the compiler optimize callers based on the knowledge +that the return value will never be null. +</p> +<a name="index-returns_005ftwice-function-attribute"></a> +<a name="index-functions-that-return-more-than-once"></a> +</dd> +<dt><code>returns_twice</code></dt> +<dd><p>The <code>returns_twice</code> 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</code> and <code>vfork</code>. +The <code>longjmp</code>-like counterpart of such function, if any, might need +to be marked with the <code>noreturn</code> attribute. +</p> +<a name="index-section-function-attribute"></a> +<a name="index-functions-in-arbitrary-sections"></a> +</dd> +<dt><code>section ("<var>section-name</var>")</code></dt> +<dd><p>Normally, the compiler places the code it generates in the <code>text</code> section. +Sometimes, however, you need additional sections, or you need certain +particular functions to appear in special sections. The <code>section</code> +attribute specifies that a function lives in a particular section. +For example, the declaration: +</p> +<div class="smallexample"> +<pre class="smallexample">extern void foobar (void) __attribute__ ((section ("bar"))); +</pre></div> + +<p>puts the function <code>foobar</code> in the <code>bar</code> section. +</p> +<p>Some file formats do not support arbitrary sections so the <code>section</code> +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. +</p> +<a name="index-sentinel-function-attribute"></a> +</dd> +<dt><code>sentinel</code></dt> +<dt><code>sentinel (<var>position</var>)</code></dt> +<dd><p>This function attribute indicates that an argument in a call to the function +is expected to be an explicit <code>NULL</code>. 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</var> argument +is specified to the attribute, the sentinel must be located at +<var>position</var> counting backwards from the end of the argument list. +</p> +<div class="smallexample"> +<pre class="smallexample">__attribute__ ((sentinel)) +is equivalent to +__attribute__ ((sentinel(0))) +</pre></div> + +<p>The attribute is automatically set with a position of 0 for the built-in +functions <code>execl</code> and <code>execlp</code>. The built-in function +<code>execle</code> has the attribute set with a position of 1. +</p> +<p>A valid <code>NULL</code> in this context is defined as zero with any object +pointer type. If your system defines the <code>NULL</code> macro with +an integer type then you need to add an explicit cast. During +installation GCC replaces the system <code><stddef.h></code> header with +a copy that redefines NULL appropriately. +</p> +<p>The warnings for missing or incorrect sentinels are enabled with +<samp>-Wformat</samp>. +</p> +<a name="index-simd-function-attribute"></a> +</dd> +<dt><code>simd</code></dt> +<dt><code>simd("<var>mask</var>")</code></dt> +<dd><p>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 +<a href="https://sourceware.org/glibc/wiki/libmvec?action=AttachFile&do=view&target=VectorABI.txt">here</a><!-- /@w -->. +</p> +<p>The optional argument <var>mask</var> may have the value +<code>notinbranch</code> or <code>inbranch</code>, +and instructs the compiler to generate non-masked or masked +clones correspondingly. By default, all clones are generated. +</p> +<p>If the attribute is specified and <code>#pragma omp declare simd</code> is +present on a declaration and the <samp>-fopenmp</samp> or <samp>-fopenmp-simd</samp> +switch is specified, then the attribute is ignored. +</p> +<a name="index-stack_005fprotect-function-attribute"></a> +</dd> +<dt><code>stack_protect</code></dt> +<dd><p>This attribute adds stack protection code to the function if +flags <samp>-fstack-protector</samp>, <samp>-fstack-protector-strong</samp> +or <samp>-fstack-protector-explicit</samp> are set. +</p> +<a name="index-no_005fstack_005fprotector-function-attribute"></a> +</dd> +<dt><code>no_stack_protector</code></dt> +<dd><p>This attribute prevents stack protection code for the function. +</p> +<a name="index-target-function-attribute"></a> +</dd> +<dt><code>target (<var>string</var>, …)</code></dt> +<dd><p>Multiple target back ends implement the <code>target</code> 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</code> prefix jointly forming the name of a machine-dependent +option. See <a href="Submodel-Options.html#Submodel-Options">Machine-Dependent Options</a>. +</p> +<p>The <code>target</code> 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</samp>’ can be used to specify target-specific +options for more than one function. See <a href="Function-Specific-Option-Pragmas.html#Function-Specific-Option-Pragmas">Function Specific Option Pragmas</a>, +for details about the pragma. +</p> +<p>For instance, on an x86, you could declare one function with the +<code>target("sse4.1,arch=core2")</code> attribute and another with +<code>target("sse4a,arch=amdfam10")</code>. This is equivalent to +compiling the first function with <samp>-msse4.1</samp> and +<samp>-march=core2</samp> options, and the second function with +<samp>-msse4a</samp> and <samp>-march=amdfam10</samp> 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</code> on x86 to determine what feature bits and architecture +family are used). +</p> +<div class="smallexample"> +<pre class="smallexample">int core2_func (void) __attribute__ ((__target__ ("arch=core2"))); +int sse3_func (void) __attribute__ ((__target__ ("sse3"))); +</pre></div> + +<p>Providing multiple strings as arguments separated by commas to specify +multiple options is equivalent to separating the option suffixes with +a comma (‘<samp>,</samp>’) within a single string. Spaces are not permitted +within the strings. +</p> +<p>The options supported are specific to each target; refer to <a href="x86-Function-Attributes.html#x86-Function-Attributes">x86 Function Attributes</a>, <a href="PowerPC-Function-Attributes.html#PowerPC-Function-Attributes">PowerPC Function Attributes</a>, +<a href="ARM-Function-Attributes.html#ARM-Function-Attributes">ARM Function Attributes</a>, <a href="AArch64-Function-Attributes.html#AArch64-Function-Attributes">AArch64 Function Attributes</a>, +<a href="Nios-II-Function-Attributes.html#Nios-II-Function-Attributes">Nios II Function Attributes</a>, and <a href="S_002f390-Function-Attributes.html#S_002f390-Function-Attributes">S/390 Function Attributes</a> +for details. +</p> +<a name="index-symver-function-attribute"></a> +</dd> +<dt><code>symver ("<var>name2</var>@<var>nodename</var>")</code></dt> +<dd><p>On ELF targets this attribute creates a symbol version. The <var>name2</var> part +of the parameter is the actual name of the symbol by which it will be +externally referenced. The <code>nodename</code> 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. +</p> +<div class="smallexample"> +<pre class="smallexample">__attribute__ ((__symver__ ("foo@VERS_1"))) int +foo_v1 (void) +{ +} +</pre></div> + +<p>Will produce a <code>.symver foo_v1, foo@VERS_1</code> directive in the assembler +output. +</p> +<p>One can also define multiple version for a given symbol +(starting from binutils 2.35). +</p> +<div class="smallexample"> +<pre class="smallexample">__attribute__ ((__symver__ ("foo@VERS_2"), __symver__ ("foo@VERS_3"))) +int symver_foo_v1 (void) +{ +} +</pre></div> + +<p>This example creates a symbol name <code>symver_foo_v1</code> +which will be version <code>VERS_2</code> and <code>VERS_3</code> of <code>foo</code>. +</p> +<p>If you have an older release of binutils, then symbol alias needs to +be used: +</p> +<div class="smallexample"> +<pre class="smallexample">__attribute__ ((__symver__ ("foo@VERS_2"))) +int foo_v1 (void) +{ + return 0; +} + +__attribute__ ((__symver__ ("foo@VERS_3"))) +__attribute__ ((alias ("foo_v1"))) +int symver_foo_v1 (void); +</pre></div> + +<p>Finally if the parameter is <code>"<var>name2</var>@@<var>nodename</var>"</code> then in +addition to creating a symbol version (as if +<code>"<var>name2</var>@<var>nodename</var>"</code> was used) the version will be also used +to resolve <var>name2</var> by the linker. +</p> +<a name="index-tainted_005fargs-function-attribute"></a> +</dd> +<dt><code>tainted_args</code></dt> +<dd><p>The <code>tainted_args</code> 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. +</p> +<p>The analyzer will pay particular attention to such functions when both +<samp>-fanalyzer</samp> and <samp>-fanalyzer-checker=taint</samp> are supplied, +potentially issuing warnings guarded by +<samp>-Wanalyzer-tainted-allocation-size</samp>, +<samp>-Wanalyzer-tainted-array-index</samp>, +<samp>-Wanalyzer-tainted-divisor</samp>, +<samp>-Wanalyzer-tainted-offset</samp>, +and <samp>-Wanalyzer-tainted-size</samp>. +</p> +<a name="index-target_005fclones-function-attribute"></a> +</dd> +<dt><code>target_clones (<var>options</var>)</code></dt> +<dd><p>The <code>target_clones</code> 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</code> attribute. +</p> +<p>For instance, on an x86, you could compile a function with +<code>target_clones("sse4.1,avx")</code>. GCC creates two function clones, +one compiled with <samp>-msse4.1</samp> and another with <samp>-mavx</samp>. +</p> +<p>On a PowerPC, you can compile a function with +<code>target_clones("cpu=power9,default")</code>. GCC will create two +function clones, one compiled with <samp>-mcpu=power9</samp> 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</code> attribute. +</p> +<p>It also creates a resolver function (see +the <code>ifunc</code> 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</code> attribute. +</p> +<p>Note that any subsequent call of a function without <code>target_clone</code> +from a <code>target_clone</code> caller will not lead to copying +(target clone) of the called function. +If you want to enforce such behaviour, +we recommend declaring the calling function with the <code>flatten</code> attribute? +</p> +<a name="index-unused-function-attribute"></a> +</dd> +<dt><code>unused</code></dt> +<dd><p>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. +</p> +<a name="index-used-function-attribute"></a> +</dd> +<dt><code>used</code></dt> +<dd><p>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. +</p> +<p>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. +</p> +<a name="index-retain-function-attribute"></a> +</dd> +<dt><code>retain</code></dt> +<dd><p>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</code> attribute, or the <code>-ffunction-sections</code> +option), will be placed in new, unique sections. +</p> +<p>This additional functionality requires Binutils version 2.36 or later. +</p> +<a name="index-visibility-function-attribute"></a> +</dd> +<dt><code>visibility ("<var>visibility_type</var>")</code></dt> +<dd><p>This attribute affects the linkage of the declaration to which it is attached. +It can be applied to variables (see <a href="Common-Variable-Attributes.html#Common-Variable-Attributes">Common Variable Attributes</a>) and types +(see <a href="Common-Type-Attributes.html#Common-Type-Attributes">Common Type Attributes</a>) as well as functions. +</p> +<p>There are four supported <var>visibility_type</var> values: default, +hidden, protected or internal visibility. +</p> +<div class="smallexample"> +<pre class="smallexample">void __attribute__ ((visibility ("protected"))) +f () { /* <span class="roman">Do something.</span> */; } +int i __attribute__ ((visibility ("hidden"))); +</pre></div> + +<p>The possible values of <var>visibility_type</var> correspond to the +visibility settings in the ELF gABI. +</p> +<dl compact="compact"> +<dt><code>default</code></dt> +<dd><p>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. +</p> +<p>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. +</p> +<p>On Darwin, default visibility means that the declaration is visible to +other modules. +</p> +<p>Default visibility corresponds to “external linkage” in the language. +</p> +</dd> +<dt><code>hidden</code></dt> +<dd><p>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. +</p> +</dd> +<dt><code>internal</code></dt> +<dd><p>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 +<em>never</em> 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. +</p> +</dd> +<dt><code>protected</code></dt> +<dd><p>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. +</p> +</dd> +</dl> + +<p>All visibilities are supported on many, but not all, ELF targets +(supported when the assembler supports the ‘<samp>.visibility</samp>’ +pseudo-op). Default visibility is supported everywhere. Hidden +visibility is supported on Darwin targets. +</p> +<p>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. +</p> +<p>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. +</p> +<p>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. +</p> +<p>A C++ namespace declaration can also have the visibility attribute. +</p> +<div class="smallexample"> +<pre class="smallexample">namespace nspace1 __attribute__ ((visibility ("protected"))) +{ /* <span class="roman">Do something.</span> */; } +</pre></div> + +<p>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</samp>’ before and after the namespace +definition (see <a href="Visibility-Pragmas.html#Visibility-Pragmas">Visibility Pragmas</a>). +</p> +<p>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. +</p> +<p>If both the template and enclosing class have explicit visibility, the +visibility from the template is used. +</p> +<a name="index-warn_005funused_005fresult-function-attribute"></a> +</dd> +<dt><code>warn_unused_result</code></dt> +<dd><p>The <code>warn_unused_result</code> 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</code>. +</p> +<div class="smallexample"> +<pre class="smallexample">int fn () __attribute__ ((warn_unused_result)); +int foo () +{ + if (fn () < 0) return -1; + fn (); + return 0; +} +</pre></div> + +<p>results in warning on line 5. +</p> +<a name="index-weak-function-attribute"></a> +</dd> +<dt><code>weak</code></dt> +<dd><p>The <code>weak</code> 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. +</p> +<a name="index-weakref-function-attribute"></a> +</dd> +<dt><code>weakref</code></dt> +<dt><code>weakref ("<var>target</var>")</code></dt> +<dd><p>The <code>weakref</code> attribute marks a declaration as a weak reference. +Without arguments, it should be accompanied by an <code>alias</code> attribute +naming the target symbol. Alternatively, <var>target</var> may be given as +an argument to <code>weakref</code> itself, naming the target definition of +the alias. The <var>target</var> 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</code> implicitly marks the declared symbol as <code>weak</code>. Without +a <var>target</var> given as an argument to <code>weakref</code> or to <code>alias</code>, +<code>weakref</code> is equivalent to <code>weak</code> (in that case the declaration +may be <code>extern</code>). +</p> +<div class="smallexample"> +<pre class="smallexample">/* Given the declaration: */ +extern int y (void); + +/* the following... */ +static int x (void) __attribute__ ((weakref ("y"))); + +/* is equivalent to... */ +static int x (void) __attribute__ ((weakref, alias ("y"))); + +/* or, alternatively, to... */ +static int x (void) __attribute__ ((weakref)); +static int x (void) __attribute__ ((alias ("y"))); +</pre></div> + +<p>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</code> +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. +</p> +<p>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</code>) on them. +</p> +<p>A declaration to which <code>weakref</code> is attached and that is associated +with a named <code>target</code> must be <code>static</code>. +</p> +<a name="index-zero_005fcall_005fused_005fregs-function-attribute"></a> +</dd> +<dt><code>zero_call_used_regs ("<var>choice</var>")</code></dt> +<dd> +<p>The <code>zero_call_used_regs</code> attribute causes the compiler to zero +a subset of all call-used registers<a name="DOCF7" href="#FOOT7"><sup>7</sup></a> at function return. +This is used to increase program security by either mitigating +Return-Oriented Programming (ROP) attacks or preventing information leakage +through registers. +</p> +<p>In order to satisfy users with different security needs and control the +run-time overhead at the same time, the <var>choice</var> parameter provides a +flexible way to choose the subset of the call-used registers to be zeroed. +The three basic values of <var>choice</var> are: +</p> +<ul> +<li> ‘<samp>skip</samp>’ doesn’t zero any call-used registers. + +</li><li> ‘<samp>used</samp>’ 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. + +</li><li> ‘<samp>all</samp>’ zeros all call-used registers. +</li></ul> + +<p>In addition to these three basic choices, it is possible to modify +‘<samp>used</samp>’ or ‘<samp>all</samp>’ as follows: +</p> +<ul> +<li> Adding ‘<samp>-gpr</samp>’ restricts the zeroing to general-purpose registers. + +</li><li> Adding ‘<samp>-arg</samp>’ 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. +</li></ul> + +<p>The modifiers can be used individually or together. If they are used +together, they must appear in the order above. +</p> +<p>The full list of <var>choice</var>s is therefore: +</p> +<dl compact="compact"> +<dt><code>skip</code></dt> +<dd><p>doesn’t zero any call-used register. +</p> +</dd> +<dt><code>used</code></dt> +<dd><p>only zeros call-used registers that are used in the function. +</p> +</dd> +<dt><code>used-gpr</code></dt> +<dd><p>only zeros call-used general purpose registers that are used in the function. +</p> +</dd> +<dt><code>used-arg</code></dt> +<dd><p>only zeros call-used registers that are used in the function and pass arguments. +</p> +</dd> +<dt><code>used-gpr-arg</code></dt> +<dd><p>only zeros call-used general purpose registers that are used in the function +and pass arguments. +</p> +</dd> +<dt><code>all</code></dt> +<dd><p>zeros all call-used registers. +</p> +</dd> +<dt><code>all-gpr</code></dt> +<dd><p>zeros all call-used general purpose registers. +</p> +</dd> +<dt><code>all-arg</code></dt> +<dd><p>zeros all call-used registers that pass arguments. +</p> +</dd> +<dt><code>all-gpr-arg</code></dt> +<dd><p>zeros all call-used general purpose registers that pass +arguments. +</p></dd> +</dl> + +<p>Of this list, ‘<samp>used-arg</samp>’, ‘<samp>used-gpr-arg</samp>’, ‘<samp>all-arg</samp>’, +and ‘<samp>all-gpr-arg</samp>’ are mainly used for ROP mitigation. +</p> +<p>The default for the attribute is controlled by <samp>-fzero-call-used-regs</samp>. +</p></dd> +</dl> + + +<div class="footnote"> +<hr> +<h4 class="footnotes-heading">Footnotes</h4> + +<h3><a name="FOOT7" href="#DOCF7">(7)</a></h3> +<p>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”.</p> +</div> +<hr> +<div class="header"> +<p> +Next: <a href="AArch64-Function-Attributes.html#AArch64-Function-Attributes" accesskey="n" rel="next">AArch64 Function Attributes</a>, Up: <a href="Function-Attributes.html#Function-Attributes" accesskey="u" rel="up">Function Attributes</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Indices.html#Indices" title="Index" rel="index">Index</a>]</p> +</div> + + + +</body> +</html> |