You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
1884 lines
134 KiB
HTML
1884 lines
134 KiB
HTML
4 years ago
|
<html lang="en">
|
||
|
|
<head>
|
||
|
|
<title>Function Attributes - Using the GNU Compiler Collection (GCC)</title>
|
||
|
|
<meta http-equiv="Content-Type" content="text/html">
|
||
|
|
<meta name="description" content="Using the GNU Compiler Collection (GCC)">
|
||
|
|
<meta name="generator" content="makeinfo 4.13">
|
||
|
|
<link title="Top" rel="start" href="index.html#Top">
|
||
|
|
<link rel="up" href="C-Extensions.html#C-Extensions" title="C Extensions">
|
||
|
|
<link rel="prev" href="Mixed-Declarations.html#Mixed-Declarations" title="Mixed Declarations">
|
||
|
|
<link rel="next" href="Label-Attributes.html#Label-Attributes" title="Label Attributes">
|
||
|
|
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
|
||
|
|
<!--
|
||
|
|
Copyright (C) 1988-2015 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.-->
|
||
|
|
<meta http-equiv="Content-Style-Type" content="text/css">
|
||
|
|
<style type="text/css"><!--
|
||
|
|
pre.display { font-family:inherit }
|
||
|
|
pre.format { font-family:inherit }
|
||
|
|
pre.smalldisplay { font-family:inherit; font-size:smaller }
|
||
|
|
pre.smallformat { font-family:inherit; font-size:smaller }
|
||
|
|
pre.smallexample { font-size:smaller }
|
||
|
|
pre.smalllisp { font-size:smaller }
|
||
|
|
span.sc { font-variant:small-caps }
|
||
|
|
span.roman { font-family:serif; font-weight:normal; }
|
||
|
|
span.sansserif { font-family:sans-serif; font-weight:normal; }
|
||
|
|
--></style>
|
||
|
|
</head>
|
||
|
|
<body>
|
||
|
|
<div class="node">
|
||
|
|
<a name="Function-Attributes"></a>
|
||
|
|
<p>
|
||
|
|
Next: <a rel="next" accesskey="n" href="Label-Attributes.html#Label-Attributes">Label Attributes</a>,
|
||
|
|
Previous: <a rel="previous" accesskey="p" href="Mixed-Declarations.html#Mixed-Declarations">Mixed Declarations</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="C-Extensions.html#C-Extensions">C Extensions</a>
|
||
|
|
<hr>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<h3 class="section">6.31 Declaring Attributes of Functions</h3>
|
||
|
|
|
||
|
|
<p><a name="index-function-attributes-3034"></a><a name="index-declaring-attributes-of-functions-3035"></a><a name="index-functions-that-never-return-3036"></a><a name="index-functions-that-return-more-than-once-3037"></a><a name="index-functions-that-have-no-side-effects-3038"></a><a name="index-functions-in-arbitrary-sections-3039"></a><a name="index-functions-that-behave-like-malloc-3040"></a><a name="index-g_t_0040code_007bvolatile_007d-applied-to-function-3041"></a><a name="index-g_t_0040code_007bconst_007d-applied-to-function-3042"></a><a name="index-functions-with-_0040code_007bprintf_007d_002c-_0040code_007bscanf_007d_002c-_0040code_007bstrftime_007d-or-_0040code_007bstrfmon_007d-style-arguments-3043"></a><a name="index-functions-with-non_002dnull-pointer-arguments-3044"></a><a name="index-functions-that-are-passed-arguments-in-registers-on-x86_002d32-3045"></a><a name="index-functions-that-pop-the-argument-stack-on-x86_002d32-3046"></a><a name="index-functions-that-do-not-pop-the-argument-stack-on-x86_002d32-3047"></a><a name="index-functions-that-have-different-compilation-options-on-x86_002d32-3048"></a><a name="index-functions-that-have-different-optimization-options-3049"></a><a name="index-functions-that-are-dynamically-resolved-3050"></a>
|
||
|
|
In GNU C, you declare certain things about functions called in your program
|
||
|
|
which help the compiler optimize function calls and check your code more
|
||
|
|
carefully.
|
||
|
|
|
||
|
|
<p>The keyword <code>__attribute__</code> allows you to specify special
|
||
|
|
attributes when making a declaration. This keyword is followed by an
|
||
|
|
attribute specification inside double parentheses. The following
|
||
|
|
attributes are currently defined for functions on all targets:
|
||
|
|
<code>aligned</code>, <code>alloc_size</code>, <code>alloc_align</code>, <code>assume_aligned</code>,
|
||
|
|
<code>noreturn</code>, <code>returns_twice</code>, <code>noinline</code>, <code>noclone</code>,
|
||
|
|
<code>no_icf</code>,
|
||
|
|
<code>always_inline</code>, <code>flatten</code>, <code>pure</code>, <code>const</code>,
|
||
|
|
<code>nothrow</code>, <code>sentinel</code>, <code>format</code>, <code>format_arg</code>,
|
||
|
|
<code>no_instrument_function</code>, <code>no_split_stack</code>,
|
||
|
|
<code>section</code>, <code>constructor</code>,
|
||
|
|
<code>destructor</code>, <code>used</code>, <code>unused</code>, <code>deprecated</code>,
|
||
|
|
<code>weak</code>, <code>malloc</code>, <code>alias</code>, <code>ifunc</code>,
|
||
|
|
<code>warn_unused_result</code>, <code>nonnull</code>,
|
||
|
|
<code>returns_nonnull</code>, <code>gnu_inline</code>,
|
||
|
|
<code>externally_visible</code>, <code>hot</code>, <code>cold</code>, <code>artificial</code>,
|
||
|
|
<code>no_sanitize_address</code>, <code>no_address_safety_analysis</code>,
|
||
|
|
<code>no_sanitize_thread</code>,
|
||
|
|
<code>no_sanitize_undefined</code>, <code>no_reorder</code>, <code>bnd_legacy</code>,
|
||
|
|
<code>bnd_instrument</code>, <code>stack_protect</code>,
|
||
|
|
<code>error</code> and <code>warning</code>.
|
||
|
|
Several other attributes are defined for functions on particular
|
||
|
|
target systems. Other attributes, including <code>section</code> are
|
||
|
|
supported for variables declarations (see <a href="Variable-Attributes.html#Variable-Attributes">Variable Attributes</a>),
|
||
|
|
labels (see <a href="Label-Attributes.html#Label-Attributes">Label Attributes</a>)
|
||
|
|
and for types (see <a href="Type-Attributes.html#Type-Attributes">Type Attributes</a>).
|
||
|
|
|
||
|
|
<p>GCC plugins may provide their own attributes.
|
||
|
|
|
||
|
|
<p>You may also specify attributes with ‘<samp><span class="samp">__</span></samp>’ preceding and following
|
||
|
|
each keyword. This allows you to use them in header files without
|
||
|
|
being concerned about a possible macro of the same name. For example,
|
||
|
|
you may use <code>__noreturn__</code> instead of <code>noreturn</code>.
|
||
|
|
|
||
|
|
<p>See <a href="Attribute-Syntax.html#Attribute-Syntax">Attribute Syntax</a>, for details of the exact syntax for using
|
||
|
|
attributes.
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<!-- Keep this table alphabetized by attribute name. Treat _ as space. -->
|
||
|
|
|
||
|
|
<dt><code>alias ("</code><var>target</var><code>")</code><dd><a name="index-g_t_0040code_007balias_007d-function-attribute-3051"></a>The <code>alias</code> attribute causes the declaration to be emitted as an
|
||
|
|
alias for another symbol, which must be specified. For instance,
|
||
|
|
|
||
|
|
<pre class="smallexample"> void __f () { /* <span class="roman">Do something.</span> */; }
|
||
|
|
void f () __attribute__ ((weak, alias ("__f")));
|
||
|
|
</pre>
|
||
|
|
<p class="noindent">defines ‘<samp><span class="samp">f</span></samp>’ to be a weak alias for ‘<samp><span class="samp">__f</span></samp>’. In C++, the
|
||
|
|
mangled name for the target must be used. It is an error if ‘<samp><span class="samp">__f</span></samp>’
|
||
|
|
is not defined in the same translation unit.
|
||
|
|
|
||
|
|
<p>Not all target machines support this attribute.
|
||
|
|
|
||
|
|
<br><dt><code>aligned (</code><var>alignment</var><code>)</code><dd><a name="index-g_t_0040code_007baligned_007d-function-attribute-3052"></a>This attribute specifies a minimum alignment for the function,
|
||
|
|
measured in bytes.
|
||
|
|
|
||
|
|
<p>You cannot use this attribute to decrease the alignment of a function,
|
||
|
|
only to increase it. However, when you explicitly specify a function
|
||
|
|
alignment this overrides the effect of the
|
||
|
|
<samp><span class="option">-falign-functions</span></samp> (see <a href="Optimize-Options.html#Optimize-Options">Optimize Options</a>) option for this
|
||
|
|
function.
|
||
|
|
|
||
|
|
<p>Note that the effectiveness of <code>aligned</code> attributes may be
|
||
|
|
limited by inherent limitations in your linker. On many 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>The <code>aligned</code> attribute can also be used for variables and fields
|
||
|
|
(see <a href="Variable-Attributes.html#Variable-Attributes">Variable Attributes</a>.)
|
||
|
|
|
||
|
|
<br><dt><code>alloc_size</code><dd><a name="index-g_t_0040code_007balloc_005fsize_007d-function-attribute-3053"></a>The <code>alloc_size</code> attribute is used to tell the compiler that the
|
||
|
|
function return value points to memory, where the size is given by
|
||
|
|
one or two of the functions parameters. GCC uses this
|
||
|
|
information to improve the correctness of <code>__builtin_object_size</code>.
|
||
|
|
|
||
|
|
<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.
|
||
|
|
|
||
|
|
<p>For instance,
|
||
|
|
|
||
|
|
<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>
|
||
|
|
<p class="noindent">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.
|
||
|
|
|
||
|
|
<br><dt><code>alloc_align</code><dd><a name="index-g_t_0040code_007balloc_005falign_007d-function-attribute-3054"></a>The <code>alloc_align</code> attribute is used to tell the compiler that the
|
||
|
|
function return value points to memory, where the returned pointer minimum
|
||
|
|
alignment is given by one of the functions parameters. GCC uses this
|
||
|
|
information to improve pointer alignment analysis.
|
||
|
|
|
||
|
|
<p>The function parameter denoting the allocated alignment is specified by
|
||
|
|
one integer argument, whose number is the argument of the attribute.
|
||
|
|
Argument numbering starts at one.
|
||
|
|
|
||
|
|
<p>For instance,
|
||
|
|
|
||
|
|
<pre class="smallexample"> void* my_memalign(size_t, size_t) __attribute__((alloc_align(1)))
|
||
|
|
</pre>
|
||
|
|
<p class="noindent">declares that <code>my_memalign</code> returns memory with minimum alignment
|
||
|
|
given by parameter 1.
|
||
|
|
|
||
|
|
<br><dt><code>assume_aligned</code><dd><a name="index-g_t_0040code_007bassume_005faligned_007d-function-attribute-3055"></a>The <code>assume_aligned</code> attribute is used to tell the compiler that the
|
||
|
|
function return value points to memory, where the returned pointer minimum
|
||
|
|
alignment is given by the first argument.
|
||
|
|
If the attribute has two arguments, the second argument is misalignment offset.
|
||
|
|
|
||
|
|
<p>For instance
|
||
|
|
|
||
|
|
<pre class="smallexample"> void* my_alloc1(size_t) __attribute__((assume_aligned(16)))
|
||
|
|
void* my_alloc2(size_t) __attribute__((assume_aligned(32, 8)))
|
||
|
|
</pre>
|
||
|
|
<p class="noindent">declares that <code>my_alloc1</code> returns 16-byte aligned pointer and
|
||
|
|
that <code>my_alloc2</code> returns a pointer whose value modulo 32 is equal
|
||
|
|
to 8.
|
||
|
|
|
||
|
|
<br><dt><code>always_inline</code><dd><a name="index-g_t_0040code_007balways_005finline_007d-function-attribute-3056"></a>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.
|
||
|
|
|
||
|
|
<br><dt><code>gnu_inline</code><dd><a name="index-g_t_0040code_007bgnu_005finline_007d-function-attribute-3057"></a>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>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>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>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>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.
|
||
|
|
|
||
|
|
<br><dt><code>artificial</code><dd><a name="index-g_t_0040code_007bartificial_007d-function-attribute-3058"></a>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.
|
||
|
|
|
||
|
|
<br><dt><code>bank_switch</code><dd><a name="index-g_t_0040code_007bbank_005fswitch_007d-function-attribute_002c-M32C-3059"></a>When added to an interrupt handler with the M32C port, causes the
|
||
|
|
prologue and epilogue to use bank switching to preserve the registers
|
||
|
|
rather than saving them on the stack.
|
||
|
|
|
||
|
|
<br><dt><code>flatten</code><dd><a name="index-g_t_0040code_007bflatten_007d-function-attribute-3060"></a>Generally, inlining into a function is limited. For a function marked with
|
||
|
|
this attribute, every call inside this function is inlined, if possible.
|
||
|
|
Whether the function itself is considered for inlining depends on its size and
|
||
|
|
the current inlining parameters.
|
||
|
|
|
||
|
|
<br><dt><code>error ("</code><var>message</var><code>")</code><dd><a name="index-g_t_0040code_007berror_007d-function-attribute-3061"></a>If this 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
|
||
|
|
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.
|
||
|
|
While it is possible to leave the function undefined and thus invoke
|
||
|
|
a link failure, when using this attribute the problem is diagnosed
|
||
|
|
earlier and with exact location of the call even in presence of inline
|
||
|
|
functions or when not emitting debugging information.
|
||
|
|
|
||
|
|
<br><dt><code>warning ("</code><var>message</var><code>")</code><dd><a name="index-g_t_0040code_007bwarning_007d-function-attribute-3062"></a>If this attribute is used on a function declaration and a call to such a function
|
||
|
|
is not eliminated through dead code elimination or other optimizations, a warning
|
||
|
|
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. While it is possible to define the function with
|
||
|
|
a message in <code>.gnu.warning*</code> section, when using this attribute the problem
|
||
|
|
is diagnosed earlier and with exact location of the call even in presence
|
||
|
|
of inline functions or when not emitting debugging information.
|
||
|
|
|
||
|
|
<br><dt><code>cdecl</code><dd><a name="index-g_t_0040code_007bcdecl_007d-function-attribute_002c-x86_002d32-3063"></a><a name="index-functions-that-do-pop-the-argument-stack-on-x86_002d32-3064"></a><a name="index-mrtd-3065"></a>On the x86-32 targets, the <code>cdecl</code> attribute causes the compiler to
|
||
|
|
assume that the calling function pops off the stack space used to
|
||
|
|
pass arguments. This is
|
||
|
|
useful to override the effects of the <samp><span class="option">-mrtd</span></samp> switch.
|
||
|
|
|
||
|
|
<br><dt><code>const</code><dd><a name="index-g_t_0040code_007bconst_007d-function-attribute-3066"></a>Many functions do not examine any values except their arguments, and
|
||
|
|
have no effects except the return value. Basically this is just slightly
|
||
|
|
more strict class than the <code>pure</code> attribute below, since function is not
|
||
|
|
allowed to read global memory.
|
||
|
|
|
||
|
|
<p><a name="index-pointer-arguments-3067"></a>Note that a function that has pointer arguments and examines the data
|
||
|
|
pointed to must <em>not</em> be declared <code>const</code>. Likewise, a
|
||
|
|
function that calls a non-<code>const</code> function usually must not be
|
||
|
|
<code>const</code>. It does not make sense for a <code>const</code> function to
|
||
|
|
return <code>void</code>.
|
||
|
|
|
||
|
|
<br><dt><code>constructor</code><dt><code>destructor</code><dt><code>constructor (</code><var>priority</var><code>)</code><dt><code>destructor (</code><var>priority</var><code>)</code><dd><a name="index-g_t_0040code_007bconstructor_007d-function-attribute-3068"></a><a name="index-g_t_0040code_007bdestructor_007d-function-attribute-3069"></a>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>You may provide an optional integer 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. 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>).
|
||
|
|
|
||
|
|
<p>These attributes are not currently implemented for Objective-C.
|
||
|
|
|
||
|
|
<br><dt><code>deprecated</code><dt><code>deprecated (</code><var>msg</var><code>)</code><dd><a name="index-g_t_0040code_007bdeprecated_007d-function-attribute-3070"></a>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:
|
||
|
|
|
||
|
|
<pre class="smallexample"> int old_fn () __attribute__ ((deprecated));
|
||
|
|
int old_fn ();
|
||
|
|
int (*fn_ptr)() = old_fn;
|
||
|
|
</pre>
|
||
|
|
<p class="noindent">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>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>.)
|
||
|
|
|
||
|
|
<br><dt><code>disinterrupt</code><dd><a name="index-g_t_0040code_007bdisinterrupt_007d-function-attribute_002c-Epiphany-3071"></a><a name="index-g_t_0040code_007bdisinterrupt_007d-function-attribute_002c-MeP-3072"></a>On Epiphany and MeP targets, this attribute causes the compiler to emit
|
||
|
|
instructions to disable interrupts for the duration of the given
|
||
|
|
function.
|
||
|
|
|
||
|
|
<br><dt><code>dllexport</code><dd><a name="index-g_t_0040code_007bdllexport_007d-function-attribute-3073"></a><a name="index-g_t_0040code_007b_005f_005fdeclspec_0028dllexport_0029_007d-3074"></a>On Microsoft Windows targets and Symbian OS targets the
|
||
|
|
<code>dllexport</code> attribute causes the compiler to provide a global
|
||
|
|
pointer to a pointer in a DLL, so that it can be referenced with the
|
||
|
|
<code>dllimport</code> attribute. On Microsoft Windows targets, the pointer
|
||
|
|
name is formed by combining <code>_imp__</code> and the function or variable
|
||
|
|
name.
|
||
|
|
|
||
|
|
<p>You can use <code>__declspec(dllexport)</code> as a synonym for
|
||
|
|
<code>__attribute__ ((dllexport))</code> for compatibility with other
|
||
|
|
compilers.
|
||
|
|
|
||
|
|
<p>On systems that support the <code>visibility</code> attribute, this
|
||
|
|
attribute also implies “default” visibility. It is an error to
|
||
|
|
explicitly specify any other visibility.
|
||
|
|
|
||
|
|
<p>GCC's default behavior is to emit all inline functions with the
|
||
|
|
<code>dllexport</code> attribute. Since this can cause object file-size bloat,
|
||
|
|
you can use <samp><span class="option">-fno-keep-inline-dllexport</span></samp>, which tells GCC to
|
||
|
|
ignore the attribute for inlined functions unless the
|
||
|
|
<samp><span class="option">-fkeep-inline-functions</span></samp> flag is used instead.
|
||
|
|
|
||
|
|
<p>The attribute is ignored for undefined symbols.
|
||
|
|
|
||
|
|
<p>When applied to C++ classes, the attribute marks defined non-inlined
|
||
|
|
member functions and static data members as exports. Static consts
|
||
|
|
initialized in-class are not marked unless they are also defined
|
||
|
|
out-of-class.
|
||
|
|
|
||
|
|
<p>For Microsoft Windows targets there are alternative methods for
|
||
|
|
including the symbol in the DLL's export table such as using a
|
||
|
|
<samp><span class="file">.def</span></samp> file with an <code>EXPORTS</code> section or, with GNU ld, using
|
||
|
|
the <samp><span class="option">--export-all</span></samp> linker flag.
|
||
|
|
|
||
|
|
<br><dt><code>dllimport</code><dd><a name="index-g_t_0040code_007bdllimport_007d-function-attribute-3075"></a><a name="index-g_t_0040code_007b_005f_005fdeclspec_0028dllimport_0029_007d-3076"></a>On Microsoft Windows and Symbian OS targets, the <code>dllimport</code>
|
||
|
|
attribute causes the compiler to reference a function or variable via
|
||
|
|
a global pointer to a pointer that is set up by the DLL exporting the
|
||
|
|
symbol. The attribute implies <code>extern</code>. On Microsoft Windows
|
||
|
|
targets, the pointer name is formed by combining <code>_imp__</code> and the
|
||
|
|
function or variable name.
|
||
|
|
|
||
|
|
<p>You can use <code>__declspec(dllimport)</code> as a synonym for
|
||
|
|
<code>__attribute__ ((dllimport))</code> for compatibility with other
|
||
|
|
compilers.
|
||
|
|
|
||
|
|
<p>On systems that support the <code>visibility</code> attribute, this
|
||
|
|
attribute also implies “default” visibility. It is an error to
|
||
|
|
explicitly specify any other visibility.
|
||
|
|
|
||
|
|
<p>Currently, the attribute is ignored for inlined functions. If the
|
||
|
|
attribute is applied to a symbol <em>definition</em>, an error is reported.
|
||
|
|
If a symbol previously declared <code>dllimport</code> is later defined, the
|
||
|
|
attribute is ignored in subsequent references, and a warning is emitted.
|
||
|
|
The attribute is also overridden by a subsequent declaration as
|
||
|
|
<code>dllexport</code>.
|
||
|
|
|
||
|
|
<p>When applied to C++ classes, the attribute marks non-inlined
|
||
|
|
member functions and static data members as imports. However, the
|
||
|
|
attribute is ignored for virtual methods to allow creation of vtables
|
||
|
|
using thunks.
|
||
|
|
|
||
|
|
<p>On the SH Symbian OS target the <code>dllimport</code> attribute also has
|
||
|
|
another affect—it can cause the vtable and run-time type information
|
||
|
|
for a class to be exported. This happens when the class has a
|
||
|
|
dllimported constructor or a non-inline, non-pure virtual function
|
||
|
|
and, for either of those two conditions, the class also has an inline
|
||
|
|
constructor or destructor and has a key function that is defined in
|
||
|
|
the current translation unit.
|
||
|
|
|
||
|
|
<p>For Microsoft Windows targets the use of the <code>dllimport</code>
|
||
|
|
attribute on functions is not necessary, but provides a small
|
||
|
|
performance benefit by eliminating a thunk in the DLL. The use of the
|
||
|
|
<code>dllimport</code> attribute on imported variables can be avoided by passing the
|
||
|
|
<samp><span class="option">--enable-auto-import</span></samp> switch to the GNU linker. As with
|
||
|
|
functions, using the attribute for a variable eliminates a thunk in
|
||
|
|
the DLL.
|
||
|
|
|
||
|
|
<p>One drawback to using this attribute is that a pointer to a
|
||
|
|
<em>variable</em> marked as <code>dllimport</code> cannot be used as a constant
|
||
|
|
address. However, a pointer to a <em>function</em> with the
|
||
|
|
<code>dllimport</code> attribute can be used as a constant initializer; in
|
||
|
|
this case, the address of a stub function in the import lib is
|
||
|
|
referenced. On Microsoft Windows targets, the attribute can be disabled
|
||
|
|
for functions by setting the <samp><span class="option">-mnop-fun-dllimport</span></samp> flag.
|
||
|
|
|
||
|
|
<br><dt><code>exception</code><dd><a name="index-g_t_0040code_007bexception_007d-function-attribute-3077"></a><a name="index-exception-handler-functions_002c-NDS32-3078"></a>Use this attribute on the NDS32 target to indicate that the specified function
|
||
|
|
is an exception handler. The compiler will generate corresponding sections
|
||
|
|
for use in an exception handler.
|
||
|
|
|
||
|
|
<br><dt><code>exception_handler</code><dd><a name="index-g_t_0040code_007bexception_005fhandler_007d-function-attribute-3079"></a><a name="index-exception-handler-functions_002c-Blackfin-3080"></a>Use this attribute on the Blackfin to indicate that the specified function
|
||
|
|
is an exception handler. The compiler generates function entry and
|
||
|
|
exit sequences suitable for use in an exception handler when this
|
||
|
|
attribute is present.
|
||
|
|
|
||
|
|
<br><dt><code>externally_visible</code><dd><a name="index-g_t_0040code_007bexternally_005fvisible_007d-function-attribute-3081"></a>This attribute, attached to a global variable or function, nullifies
|
||
|
|
the effect of the <samp><span class="option">-fwhole-program</span></samp> command-line option, so the
|
||
|
|
object remains visible outside the current compilation unit.
|
||
|
|
|
||
|
|
<p>If <samp><span class="option">-fwhole-program</span></samp> is used together with <samp><span class="option">-flto</span></samp> and
|
||
|
|
<samp><span class="command">gold</span></samp> is used as the linker plugin,
|
||
|
|
<code>externally_visible</code> attributes are automatically added to functions
|
||
|
|
(not variable yet due to a current <samp><span class="command">gold</span></samp> issue)
|
||
|
|
that are accessed outside of LTO objects according to resolution file
|
||
|
|
produced by <samp><span class="command">gold</span></samp>.
|
||
|
|
For other linkers that cannot generate resolution file,
|
||
|
|
explicit <code>externally_visible</code> attributes are still necessary.
|
||
|
|
|
||
|
|
<br><dt><code>far</code><dd><a name="index-g_t_0040code_007bfar_007d-function-attribute-3082"></a>
|
||
|
|
On MeP targets this causes the compiler to use a calling convention
|
||
|
|
that assumes the called function is too far away for the built-in
|
||
|
|
addressing modes.
|
||
|
|
|
||
|
|
<br><dt><code>fast_interrupt</code><dd><a name="index-g_t_0040code_007bfast_005finterrupt_007d-function-attribute_002c-M32C-3083"></a><a name="index-g_t_0040code_007bfast_005finterrupt_007d-function-attribute_002c-RX-3084"></a>Use this attribute on the M32C and RX ports to indicate that the specified
|
||
|
|
function is a fast interrupt handler. This is just like the
|
||
|
|
<code>interrupt</code> attribute, except that <code>freit</code> is used to return
|
||
|
|
instead of <code>reit</code>.
|
||
|
|
|
||
|
|
<br><dt><code>fastcall</code><dd><a name="index-g_t_0040code_007bfastcall_007d-function-attribute_002c-x86_002d32-3085"></a><a name="index-functions-that-pop-the-argument-stack-on-x86_002d32-3086"></a>On x86-32 targets, the <code>fastcall</code> attribute causes the compiler to
|
||
|
|
pass the first argument (if of integral type) in the register ECX and
|
||
|
|
the second argument (if of integral type) in the register EDX. Subsequent
|
||
|
|
and other typed arguments are passed on the stack. The called function
|
||
|
|
pops the arguments off the stack. If the number of arguments is variable all
|
||
|
|
arguments are pushed on the stack.
|
||
|
|
|
||
|
|
<br><dt><code>thiscall</code><dd><a name="index-g_t_0040code_007bthiscall_007d-function-attribute_002c-x86_002d32-3087"></a><a name="index-functions-that-pop-the-argument-stack-on-x86_002d32-3088"></a>On x86-32 targets, the <code>thiscall</code> attribute causes the compiler to
|
||
|
|
pass the first argument (if of integral type) in the register ECX.
|
||
|
|
Subsequent and other typed arguments are passed on the stack. The called
|
||
|
|
function pops the arguments off the stack.
|
||
|
|
If the number of arguments is variable all arguments are pushed on the
|
||
|
|
stack.
|
||
|
|
The <code>thiscall</code> attribute is intended for C++ non-static member functions.
|
||
|
|
As a GCC extension, this calling convention can be used for C functions
|
||
|
|
and for static member methods.
|
||
|
|
|
||
|
|
<br><dt><code>format (</code><var>archetype</var><code>, </code><var>string-index</var><code>, </code><var>first-to-check</var><code>)</code><dd><a name="index-g_t_0040code_007bformat_007d-function-attribute-3089"></a><a name="index-Wformat-3090"></a>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:
|
||
|
|
|
||
|
|
<pre class="smallexample"> extern int
|
||
|
|
my_printf (void *my_object, const char *my_format, ...)
|
||
|
|
__attribute__ ((format (printf, 2, 3)));
|
||
|
|
</pre>
|
||
|
|
<p class="noindent">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>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><span class="samp">gnu_</span></samp>’ always refer
|
||
|
|
to the formats accepted by the GNU C Library. On Microsoft Windows
|
||
|
|
targets, values prefixed with ‘<samp><span class="samp">ms_</span></samp>’ refer to the formats accepted by the
|
||
|
|
<samp><span class="file">msvcrt.dll</span></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>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-3091"></a><a name="index-fno_002dbuiltin-3092"></a>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><span class="option">-ffreestanding</span></samp> or <samp><span class="option">-fno-builtin</span></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><span class="option">-Wformat</span></samp>), so there is no need to
|
||
|
|
modify the header file <samp><span class="file">stdio.h</span></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>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>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>.
|
||
|
|
|
||
|
|
<br><dt><code>format_arg (</code><var>string-index</var><code>)</code><dd><a name="index-g_t_0040code_007bformat_005farg_007d-function-attribute-3093"></a><a name="index-Wformat_002dnonliteral-3094"></a>The <code>format_arg</code> attribute specifies that a function takes a format
|
||
|
|
string 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). For example, the
|
||
|
|
declaration:
|
||
|
|
|
||
|
|
<pre class="smallexample"> extern char *
|
||
|
|
my_dgettext (char *my_domain, const char *my_format)
|
||
|
|
__attribute__ ((format_arg (2)));
|
||
|
|
</pre>
|
||
|
|
<p class="noindent">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><span class="option">-Wformat-nonliteral</span></samp> is used, but the calls could not be checked
|
||
|
|
without the attribute.
|
||
|
|
|
||
|
|
<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>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><span class="option">-ansi</span></samp> or an appropriate <samp><span class="option">-std</span></samp> option, or
|
||
|
|
<samp><span class="option">-ffreestanding</span></samp> or <samp><span class="option">-fno-builtin</span></samp>
|
||
|
|
is used. See <a href="C-Dialect-Options.html#C-Dialect-Options">Options Controlling C Dialect</a>.
|
||
|
|
|
||
|
|
<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>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>.
|
||
|
|
|
||
|
|
<br><dt><code>function_vector</code><dd><a name="index-g_t_0040code_007bfunction_005fvector_007d-function-attribute_002c-H8_002f300-3095"></a><a name="index-g_t_0040code_007bfunction_005fvector_007d-function-attribute_002c-M16C_002fM32C-3096"></a><a name="index-g_t_0040code_007bfunction_005fvector_007d-function-attribute_002c-SH-3097"></a><a name="index-calling-functions-through-the-function-vector-on-H8_002f300_002c-M16C_002c-M32C-and-SH2A-processors-3098"></a>Use this attribute on the H8/300, H8/300H, and H8S to indicate that the specified
|
||
|
|
function should be called through the function vector. Calling a
|
||
|
|
function through the function vector reduces code size, however;
|
||
|
|
the function vector has a limited size (maximum 128 entries on the H8/300
|
||
|
|
and 64 entries on the H8/300H and H8S) and shares space with the interrupt vector.
|
||
|
|
|
||
|
|
<p>On SH2A targets, this attribute declares a function to be called using the
|
||
|
|
TBR relative addressing mode. The argument to this attribute is the entry
|
||
|
|
number of the same function in a vector table containing all the TBR
|
||
|
|
relative addressable functions. For correct operation the TBR must be setup
|
||
|
|
accordingly to point to the start of the vector table before any functions with
|
||
|
|
this attribute are invoked. Usually a good place to do the initialization is
|
||
|
|
the startup routine. The TBR relative vector table can have at max 256 function
|
||
|
|
entries. The jumps to these functions are generated using a SH2A specific,
|
||
|
|
non delayed branch instruction JSR/N @(disp8,TBR). You must use GAS and GLD
|
||
|
|
from GNU binutils version 2.7 or later for this attribute to work correctly.
|
||
|
|
|
||
|
|
<p>Please refer the example of M16C target, to see the use of this
|
||
|
|
attribute while declaring a function,
|
||
|
|
|
||
|
|
<p>In an application, for a function being called once, this attribute
|
||
|
|
saves at least 8 bytes of code; and if other successive calls are being
|
||
|
|
made to the same function, it saves 2 bytes of code per each of these
|
||
|
|
calls.
|
||
|
|
|
||
|
|
<p>On M16C/M32C targets, the <code>function_vector</code> attribute declares a
|
||
|
|
special page subroutine call function. Use of this attribute reduces
|
||
|
|
the code size by 2 bytes for each call generated to the
|
||
|
|
subroutine. The argument to the attribute is the vector number entry
|
||
|
|
from the special page vector table which contains the 16 low-order
|
||
|
|
bits of the subroutine's entry address. Each vector table has special
|
||
|
|
page number (18 to 255) that is used in <code>jsrs</code> instructions.
|
||
|
|
Jump addresses of the routines are generated by adding 0x0F0000 (in
|
||
|
|
case of M16C targets) or 0xFF0000 (in case of M32C targets), to the
|
||
|
|
2-byte addresses set in the vector table. Therefore you need to ensure
|
||
|
|
that all the special page vector routines should get mapped within the
|
||
|
|
address range 0x0F0000 to 0x0FFFFF (for M16C) and 0xFF0000 to 0xFFFFFF
|
||
|
|
(for M32C).
|
||
|
|
|
||
|
|
<p>In the following example 2 bytes are saved for each call to
|
||
|
|
function <code>foo</code>.
|
||
|
|
|
||
|
|
<pre class="smallexample"> void foo (void) __attribute__((function_vector(0x18)));
|
||
|
|
void foo (void)
|
||
|
|
{
|
||
|
|
}
|
||
|
|
|
||
|
|
void bar (void)
|
||
|
|
{
|
||
|
|
foo();
|
||
|
|
}
|
||
|
|
</pre>
|
||
|
|
<p>If functions are defined in one file and are called in another file,
|
||
|
|
then be sure to write this declaration in both files.
|
||
|
|
|
||
|
|
<p>This attribute is ignored for R8C target.
|
||
|
|
|
||
|
|
<br><dt><code>ifunc ("</code><var>resolver</var><code>")</code><dd><a name="index-g_t_0040code_007bifunc_007d-function-attribute-3099"></a>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 can 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's declaration is be a
|
||
|
|
function returning pointer to void function returning void:
|
||
|
|
|
||
|
|
<pre class="smallexample"> void *my_memcpy (void *dst, const void *src, size_t len)
|
||
|
|
{
|
||
|
|
...
|
||
|
|
}
|
||
|
|
|
||
|
|
static void (*resolve_memcpy (void)) (void)
|
||
|
|
{
|
||
|
|
return my_memcpy; // we'll just always select this routine
|
||
|
|
}
|
||
|
|
</pre>
|
||
|
|
<p class="noindent">The exported header file declaring the function the user calls would
|
||
|
|
contain:
|
||
|
|
|
||
|
|
<pre class="smallexample"> extern void *memcpy (void *, const void *, size_t);
|
||
|
|
</pre>
|
||
|
|
<p class="noindent">allowing the user to call this as a regular function, unaware of the
|
||
|
|
implementation. Finally, the indirect function needs to be defined in
|
||
|
|
the same translation unit as the resolver function:
|
||
|
|
|
||
|
|
<pre class="smallexample"> void *memcpy (void *, const void *, size_t)
|
||
|
|
__attribute__ ((ifunc ("resolve_memcpy")));
|
||
|
|
</pre>
|
||
|
|
<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.
|
||
|
|
|
||
|
|
<br><dt><code>interrupt</code><dd><a name="index-g_t_0040code_007binterrupt_007d-function-attribute_002c-ARC-3100"></a><a name="index-g_t_0040code_007binterrupt_007d-function-attribute_002c-ARM-3101"></a><a name="index-g_t_0040code_007binterrupt_007d-function-attribute_002c-AVR-3102"></a><a name="index-g_t_0040code_007binterrupt_007d-function-attribute_002c-CR16-3103"></a><a name="index-g_t_0040code_007binterrupt_007d-function-attribute_002c-Epiphany-3104"></a><a name="index-g_t_0040code_007binterrupt_007d-function-attribute_002c-M32C-3105"></a><a name="index-g_t_0040code_007binterrupt_007d-function-attribute_002c-M32R_002fD-3106"></a><a name="index-g_t_0040code_007binterrupt_007d-function-attribute_002c-m68k-3107"></a><a name="index-g_t_0040code_007binterrupt_007d-function-attribute_002c-MeP-3108"></a><a name="index-g_t_0040code_007binterrupt_007d-function-attribute_002c-MIPS-3109"></a><a name="index-g_t_0040code_007binterrupt_007d-function-attribute_002c-MSP430-3110"></a><a name="index-g_t_0040code_007binterrupt_007d-function-attribute_002c-NDS32-3111"></a><a name="index-g_t_0040code_007binterrupt_007d-function-attribute_002c-RL78-3112"></a><a name="index-g_t_0040code_007binterrupt_007d-function-attribute_002c-RX-3113"></a><a name="index-g_t_0040code_007binterrupt_007d-function-attribute_002c-Visium-3114"></a><a name="index-g_t_0040code_007binterrupt_007d-function-attribute_002c-Xstormy16-3115"></a>Use this attribute on the ARC, ARM, AVR, CR16, Epiphany, M32C, M32R/D,
|
||
|
|
m68k, MeP, MIPS, MSP430, NDS32, RL78, RX, Visium and Xstormy16 ports to indicate
|
||
|
|
that the specified function is an interrupt handler. The compiler generates
|
||
|
|
function entry and exit sequences suitable for use in an interrupt handler
|
||
|
|
when this attribute is present. With Epiphany targets it may also generate
|
||
|
|
a special section with code to initialize the interrupt vector table.
|
||
|
|
|
||
|
|
<p>Note, interrupt handlers for the Blackfin, H8/300, H8/300H, H8S, MicroBlaze,
|
||
|
|
and SH processors can be specified via the <code>interrupt_handler</code> attribute.
|
||
|
|
|
||
|
|
<p>Note, on the ARC, you must specify the kind of interrupt to be handled
|
||
|
|
in a parameter to the interrupt attribute like this:
|
||
|
|
|
||
|
|
<pre class="smallexample"> void f () __attribute__ ((interrupt ("ilink1")));
|
||
|
|
</pre>
|
||
|
|
<p>Permissible values for this parameter are: <code>ilink1</code><!-- /@w --> and
|
||
|
|
<code>ilink2</code><!-- /@w -->.
|
||
|
|
|
||
|
|
<p>Note, on the AVR, the hardware globally disables interrupts when an
|
||
|
|
interrupt is executed. The first instruction of an interrupt handler
|
||
|
|
declared with this attribute is a <code>SEI</code> instruction to
|
||
|
|
re-enable interrupts. See also the <code>signal</code> function attribute
|
||
|
|
that does not insert a <code>SEI</code> instruction. If both <code>signal</code> and
|
||
|
|
<code>interrupt</code> are specified for the same function, <code>signal</code>
|
||
|
|
is silently ignored.
|
||
|
|
|
||
|
|
<p>Note, for the ARM, you can specify the kind of interrupt to be handled by
|
||
|
|
adding an optional parameter to the interrupt attribute like this:
|
||
|
|
|
||
|
|
<pre class="smallexample"> void f () __attribute__ ((interrupt ("IRQ")));
|
||
|
|
</pre>
|
||
|
|
<p class="noindent">Permissible values for this parameter are: <code>IRQ</code>, <code>FIQ</code>,
|
||
|
|
<code>SWI</code>, <code>ABORT</code> and <code>UNDEF</code>.
|
||
|
|
|
||
|
|
<p>On ARMv7-M the interrupt type is ignored, and the attribute means the function
|
||
|
|
may be called with a word-aligned stack pointer.
|
||
|
|
|
||
|
|
<p>Note, for the MSP430 you can provide an argument to the interrupt
|
||
|
|
attribute which specifies a name or number. If the argument is a
|
||
|
|
number it indicates the slot in the interrupt vector table (0 - 31) to
|
||
|
|
which this handler should be assigned. If the argument is a name it
|
||
|
|
is treated as a symbolic name for the vector slot. These names should
|
||
|
|
match up with appropriate entries in the linker script. By default
|
||
|
|
the names <code>watchdog</code> for vector 26, <code>nmi</code> for vector 30 and
|
||
|
|
<code>reset</code> for vector 31 are recognized.
|
||
|
|
|
||
|
|
<p>You can also use the following function attributes to modify how
|
||
|
|
normal functions interact with interrupt functions:
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><code>critical</code><dd><a name="index-g_t_0040code_007bcritical_007d-function-attribute_002c-MSP430-3116"></a>Critical functions disable interrupts upon entry and restore the
|
||
|
|
previous interrupt state upon exit. Critical functions cannot also
|
||
|
|
have the <code>naked</code> or <code>reentrant</code> attributes. They can have
|
||
|
|
the <code>interrupt</code> attribute.
|
||
|
|
|
||
|
|
<br><dt><code>reentrant</code><dd><a name="index-g_t_0040code_007breentrant_007d-function-attribute_002c-MSP430-3117"></a>Reentrant functions disable interrupts upon entry and enable them
|
||
|
|
upon exit. Reentrant functions cannot also have the <code>naked</code>
|
||
|
|
or <code>critical</code> attributes. They can have the <code>interrupt</code>
|
||
|
|
attribute.
|
||
|
|
|
||
|
|
<br><dt><code>wakeup</code><dd><a name="index-g_t_0040code_007bwakeup_007d-function-attribute_002c-MSP430-3118"></a>This attribute only applies to interrupt functions. It is silently
|
||
|
|
ignored if applied to a non-interrupt function. A wakeup interrupt
|
||
|
|
function will rouse the processor from any low-power state that it
|
||
|
|
might be in when the function exits.
|
||
|
|
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<p>On Epiphany targets one or more optional parameters can be added like this:
|
||
|
|
|
||
|
|
<pre class="smallexample"> void __attribute__ ((interrupt ("dma0, dma1"))) universal_dma_handler ();
|
||
|
|
</pre>
|
||
|
|
<p>Permissible values for these parameters are: <code>reset</code><!-- /@w -->,
|
||
|
|
<code>software_exception</code><!-- /@w -->, <code>page_miss</code><!-- /@w -->,
|
||
|
|
<code>timer0</code><!-- /@w -->, <code>timer1</code><!-- /@w -->, <code>message</code><!-- /@w -->,
|
||
|
|
<code>dma0</code><!-- /@w -->, <code>dma1</code><!-- /@w -->, <code>wand</code><!-- /@w --> and <code>swi</code><!-- /@w -->.
|
||
|
|
Multiple parameters indicate that multiple entries in the interrupt
|
||
|
|
vector table should be initialized for this function, i.e. for each
|
||
|
|
parameter <var>name</var><!-- /@w -->, a jump to the function is emitted in
|
||
|
|
the section ivt_entry_<var>name</var><!-- /@w -->. The parameter(s) may be omitted
|
||
|
|
entirely, in which case no interrupt vector table entry is provided.
|
||
|
|
|
||
|
|
<p>Note, on Epiphany targets, interrupts are enabled inside the function
|
||
|
|
unless the <code>disinterrupt</code> attribute is also specified.
|
||
|
|
|
||
|
|
<p>On Epiphany targets, you can also use the following attribute to
|
||
|
|
modify the behavior of an interrupt handler:
|
||
|
|
<dl>
|
||
|
|
<dt><code>forwarder_section</code><dd><a name="index-g_t_0040code_007bforwarder_005fsection_007d-function-attribute_002c-Epiphany-3119"></a>The interrupt handler may be in external memory which cannot be
|
||
|
|
reached by a branch instruction, so generate a local memory trampoline
|
||
|
|
to transfer control. The single parameter identifies the section where
|
||
|
|
the trampoline is placed.
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<p>The following examples are all valid uses of these attributes on
|
||
|
|
Epiphany targets:
|
||
|
|
<pre class="smallexample"> void __attribute__ ((interrupt)) universal_handler ();
|
||
|
|
void __attribute__ ((interrupt ("dma1"))) dma1_handler ();
|
||
|
|
void __attribute__ ((interrupt ("dma0, dma1"))) universal_dma_handler ();
|
||
|
|
void __attribute__ ((interrupt ("timer0"), disinterrupt))
|
||
|
|
fast_timer_handler ();
|
||
|
|
void __attribute__ ((interrupt ("dma0, dma1"), forwarder_section ("tramp")))
|
||
|
|
external_dma_handler ();
|
||
|
|
</pre>
|
||
|
|
<p>On MIPS targets, you can use the following attributes to modify the behavior
|
||
|
|
of an interrupt handler:
|
||
|
|
<dl>
|
||
|
|
<dt><code>use_shadow_register_set</code><dd><a name="index-g_t_0040code_007buse_005fshadow_005fregister_005fset_007d-function-attribute_002c-MIPS-3120"></a>Assume that the handler uses a shadow register set, instead of
|
||
|
|
the main general-purpose registers.
|
||
|
|
|
||
|
|
<br><dt><code>keep_interrupts_masked</code><dd><a name="index-g_t_0040code_007bkeep_005finterrupts_005fmasked_007d-function-attribute_002c-MIPS-3121"></a>Keep interrupts masked for the whole function. Without this attribute,
|
||
|
|
GCC tries to reenable interrupts for as much of the function as it can.
|
||
|
|
|
||
|
|
<br><dt><code>use_debug_exception_return</code><dd><a name="index-g_t_0040code_007buse_005fdebug_005fexception_005freturn_007d-function-attribute_002c-MIPS-3122"></a>Return using the <code>deret</code> instruction. Interrupt handlers that don't
|
||
|
|
have this attribute return using <code>eret</code> instead.
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<p>You can use any combination of these attributes, as shown below:
|
||
|
|
<pre class="smallexample"> void __attribute__ ((interrupt)) v0 ();
|
||
|
|
void __attribute__ ((interrupt, use_shadow_register_set)) v1 ();
|
||
|
|
void __attribute__ ((interrupt, keep_interrupts_masked)) v2 ();
|
||
|
|
void __attribute__ ((interrupt, use_debug_exception_return)) v3 ();
|
||
|
|
void __attribute__ ((interrupt, use_shadow_register_set,
|
||
|
|
keep_interrupts_masked)) v4 ();
|
||
|
|
void __attribute__ ((interrupt, use_shadow_register_set,
|
||
|
|
use_debug_exception_return)) v5 ();
|
||
|
|
void __attribute__ ((interrupt, keep_interrupts_masked,
|
||
|
|
use_debug_exception_return)) v6 ();
|
||
|
|
void __attribute__ ((interrupt, use_shadow_register_set,
|
||
|
|
keep_interrupts_masked,
|
||
|
|
use_debug_exception_return)) v7 ();
|
||
|
|
</pre>
|
||
|
|
<p>On NDS32 target, this attribute indicates that the specified function
|
||
|
|
is an interrupt handler. The compiler generates corresponding sections
|
||
|
|
for use in an interrupt handler. You can use the following attributes
|
||
|
|
to modify the behavior:
|
||
|
|
<dl>
|
||
|
|
<dt><code>nested</code><dd><a name="index-g_t_0040code_007bnested_007d-function-attribute_002c-NDS32-3123"></a>This interrupt service routine is interruptible.
|
||
|
|
<br><dt><code>not_nested</code><dd><a name="index-g_t_0040code_007bnot_005fnested_007d-function-attribute_002c-NDS32-3124"></a>This interrupt service routine is not interruptible.
|
||
|
|
<br><dt><code>nested_ready</code><dd><a name="index-g_t_0040code_007bnested_005fready_007d-function-attribute_002c-NDS32-3125"></a>This interrupt service routine is interruptible after <code>PSW.GIE</code>
|
||
|
|
(global interrupt enable) is set. This allows interrupt service routine to
|
||
|
|
finish some short critical code before enabling interrupts.
|
||
|
|
<br><dt><code>save_all</code><dd><a name="index-g_t_0040code_007bsave_005fall_007d-function-attribute_002c-NDS32-3126"></a>The system will help save all registers into stack before entering
|
||
|
|
interrupt handler.
|
||
|
|
<br><dt><code>partial_save</code><dd><a name="index-g_t_0040code_007bpartial_005fsave_007d-function-attribute_002c-NDS32-3127"></a>The system will help save caller registers into stack before entering
|
||
|
|
interrupt handler.
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<p><a name="index-g_t_0040code_007bbrk_005finterrupt_007d-function-attribute_002c-RL78-3128"></a>On RL78, use <code>brk_interrupt</code> instead of <code>interrupt</code> for
|
||
|
|
handlers intended to be used with the <code>BRK</code> opcode (i.e. those
|
||
|
|
that must end with <code>RETB</code> instead of <code>RETI</code>).
|
||
|
|
|
||
|
|
<p>On RX targets, you may specify one or more vector numbers as arguments
|
||
|
|
to the attribute, as well as naming an alternate table name.
|
||
|
|
Parameters are handled sequentially, so one handler can be assigned to
|
||
|
|
multiple entries in multiple tables. One may also pass the magic
|
||
|
|
string <code>"$default"</code> which causes the function to be used for any
|
||
|
|
unfilled slots in the current table.
|
||
|
|
|
||
|
|
<p>This example shows a simple assignment of a function to one vector in
|
||
|
|
the default table (note that preprocessor macros may be used for
|
||
|
|
chip-specific symbolic vector names):
|
||
|
|
<pre class="smallexample"> void __attribute__ ((interrupt (5))) txd1_handler ();
|
||
|
|
</pre>
|
||
|
|
<p>This example assigns a function to two slots in the default table
|
||
|
|
(using preprocessor macros defined elsewhere) and makes it the default
|
||
|
|
for the <code>dct</code> table:
|
||
|
|
<pre class="smallexample"> void __attribute__ ((interrupt (RXD1_VECT,RXD2_VECT,"dct","$default")))
|
||
|
|
txd1_handler ();
|
||
|
|
</pre>
|
||
|
|
<br><dt><code>interrupt_handler</code><dd><a name="index-g_t_0040code_007binterrupt_005fhandler_007d-function-attribute_002c-Blackfin-3129"></a><a name="index-g_t_0040code_007binterrupt_005fhandler_007d-function-attribute_002c-m68k-3130"></a><a name="index-g_t_0040code_007binterrupt_005fhandler_007d-function-attribute_002c-H8_002f300-3131"></a><a name="index-g_t_0040code_007binterrupt_005fhandler_007d-function-attribute_002c-SH-3132"></a>Use this attribute on the Blackfin, m68k, H8/300, H8/300H, H8S, and SH to
|
||
|
|
indicate that the specified function is an interrupt handler. The compiler
|
||
|
|
generates function entry and exit sequences suitable for use in an
|
||
|
|
interrupt handler when this attribute is present.
|
||
|
|
|
||
|
|
<br><dt><code>interrupt_thread</code><dd><a name="index-g_t_0040code_007binterrupt_005fthread_007d-function-attribute_002c-fido-3133"></a>Use this attribute on fido, a subarchitecture of the m68k, to indicate
|
||
|
|
that the specified function is an interrupt handler that is designed
|
||
|
|
to run as a thread. The compiler omits generate prologue/epilogue
|
||
|
|
sequences and replaces the return instruction with a <code>sleep</code>
|
||
|
|
instruction. This attribute is available only on fido.
|
||
|
|
|
||
|
|
<br><dt><code>isr</code><dd><a name="index-g_t_0040code_007bisr_007d-function-attribute_002c-ARM-3134"></a>Use this attribute on ARM to write Interrupt Service Routines. This is an
|
||
|
|
alias to the <code>interrupt</code> attribute above.
|
||
|
|
|
||
|
|
<br><dt><code>kspisusp</code><dd><a name="index-g_t_0040code_007bkspisusp_007d-function-attribute_002c-Blackfin-3135"></a><a name="index-User-stack-pointer-in-interrupts-on-the-Blackfin-3136"></a>When used together with <code>interrupt_handler</code>, <code>exception_handler</code>
|
||
|
|
or <code>nmi_handler</code>, code is generated to load the stack pointer
|
||
|
|
from the USP register in the function prologue.
|
||
|
|
|
||
|
|
<br><dt><code>l1_text</code><dd><a name="index-g_t_0040code_007bl1_005ftext_007d-function-attribute_002c-Blackfin-3137"></a>This attribute specifies a function to be placed into L1 Instruction
|
||
|
|
SRAM. The function is put into a specific section named <code>.l1.text</code>.
|
||
|
|
With <samp><span class="option">-mfdpic</span></samp>, function calls with a such function as the callee
|
||
|
|
or caller uses inlined PLT.
|
||
|
|
|
||
|
|
<br><dt><code>l2</code><dd><a name="index-g_t_0040code_007bl2_007d-function-attribute_002c-Blackfin-3138"></a>On the Blackfin, this attribute specifies a function to be placed into L2
|
||
|
|
SRAM. The function is put into a specific section named
|
||
|
|
<code>.l1.text</code>. With <samp><span class="option">-mfdpic</span></samp>, callers of such functions use
|
||
|
|
an inlined PLT.
|
||
|
|
|
||
|
|
<br><dt><code>leaf</code><dd><a name="index-g_t_0040code_007bleaf_007d-function-attribute-3139"></a>Calls to external functions with this attribute must return to the current
|
||
|
|
compilation unit only by return or by exception handling. In particular, leaf
|
||
|
|
functions are not allowed to call callback function passed to it from the current
|
||
|
|
compilation unit or directly call functions exported by the unit or longjmp
|
||
|
|
into the unit. Leaf function 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>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 can
|
||
|
|
not 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>Note that leaf functions might invoke signals and signal handlers might be
|
||
|
|
defined in the current compilation unit and use static variables. The only
|
||
|
|
compliant way to write such a signal handler is to declare such variables
|
||
|
|
<code>volatile</code>.
|
||
|
|
|
||
|
|
<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.
|
||
|
|
|
||
|
|
<br><dt><code>long_call</code><dt><code>medium_call</code><dt><code>short_call</code><dd><a name="index-g_t_0040code_007blong_005fcall_007d-function-attribute_002c-ARC-3140"></a><a name="index-g_t_0040code_007blong_005fcall_007d-function-attribute_002c-ARM-3141"></a><a name="index-g_t_0040code_007blong_005fcall_007d-function-attribute_002c-Epiphany-3142"></a><a name="index-g_t_0040code_007bmedium_005fcall_007d-function-attribute_002c-ARC-3143"></a><a name="index-g_t_0040code_007bshort_005fcall_007d-function-attribute_002c-ARC-3144"></a><a name="index-g_t_0040code_007bshort_005fcall_007d-function-attribute_002c-ARM-3145"></a><a name="index-g_t_0040code_007bshort_005fcall_007d-function-attribute_002c-Epiphany-3146"></a><a name="index-indirect-calls_002c-ARC-3147"></a><a name="index-indirect-calls_002c-ARM-3148"></a><a name="index-indirect-calls_002c-Epiphany-3149"></a>These attributes specify how a particular function is called on
|
||
|
|
ARC, ARM and Epiphany - with <code>medium_call</code> being specific to ARC.
|
||
|
|
These attributes override the
|
||
|
|
<samp><span class="option">-mlong-calls</span></samp> (see <a href="ARM-Options.html#ARM-Options">ARM Options</a> and <a href="ARC-Options.html#ARC-Options">ARC Options</a>)
|
||
|
|
and <samp><span class="option">-mmedium-calls</span></samp> (see <a href="ARC-Options.html#ARC-Options">ARC Options</a>)
|
||
|
|
command-line switches and <code>#pragma long_calls</code> settings. For ARM, the
|
||
|
|
<code>long_call</code> attribute indicates that the function might be far
|
||
|
|
away from the call site and require a different (more expensive)
|
||
|
|
calling sequence. The <code>short_call</code> attribute always places
|
||
|
|
the offset to the function from the call site into the ‘<samp><span class="samp">BL</span></samp>’
|
||
|
|
instruction directly.
|
||
|
|
|
||
|
|
<p>For ARC, a function marked with the <code>long_call</code> attribute is
|
||
|
|
always called using register-indirect jump-and-link instructions,
|
||
|
|
thereby enabling the called function to be placed anywhere within the
|
||
|
|
32-bit address space. A function marked with the <code>medium_call</code>
|
||
|
|
attribute will always be close enough to be called with an unconditional
|
||
|
|
branch-and-link instruction, which has a 25-bit offset from
|
||
|
|
the call site. A function marked with the <code>short_call</code>
|
||
|
|
attribute will always be close enough to be called with a conditional
|
||
|
|
branch-and-link instruction, which has a 21-bit offset from
|
||
|
|
the call site.
|
||
|
|
|
||
|
|
<br><dt><code>longcall</code><dt><code>shortcall</code><dd><a name="index-indirect-calls_002c-Blackfin-3150"></a><a name="index-indirect-calls_002c-PowerPC-3151"></a><a name="index-g_t_0040code_007blongcall_007d-function-attribute_002c-Blackfin-3152"></a><a name="index-g_t_0040code_007blongcall_007d-function-attribute_002c-PowerPC-3153"></a><a name="index-g_t_0040code_007bshortcall_007d-function-attribute_002c-Blackfin-3154"></a><a name="index-g_t_0040code_007bshortcall_007d-function-attribute_002c-PowerPC-3155"></a>On Blackfin and PowerPC, the <code>longcall</code> attribute
|
||
|
|
indicates that the function might be far away from the call site and
|
||
|
|
require a different (more expensive) calling sequence. The
|
||
|
|
<code>shortcall</code> attribute indicates that the function is always close
|
||
|
|
enough for the shorter calling sequence to be used. These attributes
|
||
|
|
override both the <samp><span class="option">-mlongcall</span></samp> switch and, on the RS/6000 and
|
||
|
|
PowerPC, the <code>#pragma longcall</code> setting.
|
||
|
|
|
||
|
|
<p>See <a href="RS_002f6000-and-PowerPC-Options.html#RS_002f6000-and-PowerPC-Options">RS/6000 and PowerPC Options</a>, for more information on whether long
|
||
|
|
calls are necessary.
|
||
|
|
|
||
|
|
<br><dt><code>long_call</code><dt><code>near</code><dt><code>far</code><dd><a name="index-indirect-calls_002c-MIPS-3156"></a><a name="index-g_t_0040code_007blong_005fcall_007d-function-attribute_002c-MIPS-3157"></a><a name="index-g_t_0040code_007bnear_007d-function-attribute_002c-MIPS-3158"></a><a name="index-g_t_0040code_007bfar_007d-function-attribute_002c-MIPS-3159"></a>These attributes specify how a particular function is called on MIPS.
|
||
|
|
The attributes override the <samp><span class="option">-mlong-calls</span></samp> (see <a href="MIPS-Options.html#MIPS-Options">MIPS Options</a>)
|
||
|
|
command-line switch. The <code>long_call</code> and <code>far</code> attributes are
|
||
|
|
synonyms, and cause the compiler to always call
|
||
|
|
the function by first loading its address into a register, and then using
|
||
|
|
the contents of that register. The <code>near</code> attribute has the opposite
|
||
|
|
effect; it specifies that non-PIC calls should be made using the more
|
||
|
|
efficient <code>jal</code> instruction.
|
||
|
|
|
||
|
|
<br><dt><code>malloc</code><dd><a name="index-g_t_0040code_007bmalloc_007d-function-attribute-3160"></a>This tells the compiler 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>.
|
||
|
|
|
||
|
|
<p>Using this attribute can improve optimization. Functions like
|
||
|
|
<code>malloc</code> and <code>calloc</code> have this property because they return
|
||
|
|
a pointer to uninitialized or zeroed-out storage. However, functions
|
||
|
|
like <code>realloc</code> do not have this property, as they can return a
|
||
|
|
pointer to storage containing pointers.
|
||
|
|
|
||
|
|
<br><dt><code>mips16</code><dt><code>nomips16</code><dd><a name="index-g_t_0040code_007bmips16_007d-function-attribute_002c-MIPS-3161"></a><a name="index-g_t_0040code_007bnomips16_007d-function-attribute_002c-MIPS-3162"></a>
|
||
|
|
On MIPS targets, you can use the <code>mips16</code> and <code>nomips16</code>
|
||
|
|
function attributes to locally select or turn off MIPS16 code generation.
|
||
|
|
A function with the <code>mips16</code> attribute is emitted as MIPS16 code,
|
||
|
|
while MIPS16 code generation is disabled for functions with the
|
||
|
|
<code>nomips16</code> attribute. These attributes override the
|
||
|
|
<samp><span class="option">-mips16</span></samp> and <samp><span class="option">-mno-mips16</span></samp> options on the command line
|
||
|
|
(see <a href="MIPS-Options.html#MIPS-Options">MIPS Options</a>).
|
||
|
|
|
||
|
|
<p>When compiling files containing mixed MIPS16 and non-MIPS16 code, the
|
||
|
|
preprocessor symbol <code>__mips16</code> reflects the setting on the command line,
|
||
|
|
not that within individual functions. Mixed MIPS16 and non-MIPS16 code
|
||
|
|
may interact badly with some GCC extensions such as <code>__builtin_apply</code>
|
||
|
|
(see <a href="Constructing-Calls.html#Constructing-Calls">Constructing Calls</a>).
|
||
|
|
|
||
|
|
<br><dt><code>micromips, MIPS</code><dt><code>nomicromips, MIPS</code><dd><a name="index-g_t_0040code_007bmicromips_007d-function-attribute-3163"></a><a name="index-g_t_0040code_007bnomicromips_007d-function-attribute-3164"></a>
|
||
|
|
On MIPS targets, you can use the <code>micromips</code> and <code>nomicromips</code>
|
||
|
|
function attributes to locally select or turn off microMIPS code generation.
|
||
|
|
A function with the <code>micromips</code> attribute is emitted as microMIPS code,
|
||
|
|
while microMIPS code generation is disabled for functions with the
|
||
|
|
<code>nomicromips</code> attribute. These attributes override the
|
||
|
|
<samp><span class="option">-mmicromips</span></samp> and <samp><span class="option">-mno-micromips</span></samp> options on the command line
|
||
|
|
(see <a href="MIPS-Options.html#MIPS-Options">MIPS Options</a>).
|
||
|
|
|
||
|
|
<p>When compiling files containing mixed microMIPS and non-microMIPS code, the
|
||
|
|
preprocessor symbol <code>__mips_micromips</code> reflects the setting on the
|
||
|
|
command line,
|
||
|
|
not that within individual functions. Mixed microMIPS and non-microMIPS code
|
||
|
|
may interact badly with some GCC extensions such as <code>__builtin_apply</code>
|
||
|
|
(see <a href="Constructing-Calls.html#Constructing-Calls">Constructing Calls</a>).
|
||
|
|
|
||
|
|
<br><dt><code>model (</code><var>model-name</var><code>)</code><dd><a name="index-g_t_0040code_007bmodel_007d-function-attribute_002c-M32R_002fD-3165"></a><a name="index-function-addressability-on-the-M32R_002fD-3166"></a>
|
||
|
|
On the M32R/D, use this attribute to set the addressability of an
|
||
|
|
object, and of the code generated for a function. The identifier
|
||
|
|
<var>model-name</var> is one of <code>small</code>, <code>medium</code>, or
|
||
|
|
<code>large</code>, representing each of the code models.
|
||
|
|
|
||
|
|
<p>Small model objects live in the lower 16MB of memory (so that their
|
||
|
|
addresses can be loaded with the <code>ld24</code> instruction), and are
|
||
|
|
callable with the <code>bl</code> instruction.
|
||
|
|
|
||
|
|
<p>Medium model objects may live anywhere in the 32-bit address space (the
|
||
|
|
compiler generates <code>seth/add3</code> instructions to load their addresses),
|
||
|
|
and are callable with the <code>bl</code> instruction.
|
||
|
|
|
||
|
|
<p>Large model objects may live anywhere in the 32-bit address space (the
|
||
|
|
compiler generates <code>seth/add3</code> instructions to load their addresses),
|
||
|
|
and may not be reachable with the <code>bl</code> instruction (the compiler
|
||
|
|
generates the much slower <code>seth/add3/jl</code> instruction sequence).
|
||
|
|
|
||
|
|
<br><dt><code>ms_abi</code><dt><code>sysv_abi</code><dd><a name="index-g_t_0040code_007bms_005fabi_007d-function-attribute_002c-x86-3167"></a><a name="index-g_t_0040code_007bsysv_005fabi_007d-function-attribute_002c-x86-3168"></a>
|
||
|
|
On 32-bit and 64-bit x86 targets, you can use an ABI attribute
|
||
|
|
to indicate which calling convention should be used for a function. The
|
||
|
|
<code>ms_abi</code> attribute tells the compiler to use the Microsoft ABI,
|
||
|
|
while the <code>sysv_abi</code> attribute tells the compiler to use the ABI
|
||
|
|
used on GNU/Linux and other systems. The default is to use the Microsoft ABI
|
||
|
|
when targeting Windows. On all other systems, the default is the x86/AMD ABI.
|
||
|
|
|
||
|
|
<p>Note, the <code>ms_abi</code> attribute for Microsoft Windows 64-bit targets currently
|
||
|
|
requires the <samp><span class="option">-maccumulate-outgoing-args</span></samp> option.
|
||
|
|
|
||
|
|
<br><dt><code>callee_pop_aggregate_return (</code><var>number</var><code>)</code><dd><a name="index-g_t_0040code_007bcallee_005fpop_005faggregate_005freturn_007d-function-attribute_002c-x86-3169"></a>
|
||
|
|
On x86-32 targets, you can use this attribute to control how
|
||
|
|
aggregates are returned in memory. If the caller is responsible for
|
||
|
|
popping the hidden pointer together with the rest of the arguments, specify
|
||
|
|
<var>number</var> equal to zero. If callee is responsible for popping the
|
||
|
|
hidden pointer, specify <var>number</var> equal to one.
|
||
|
|
|
||
|
|
<p>The default x86-32 ABI assumes that the callee pops the
|
||
|
|
stack for hidden pointer. However, on x86-32 Microsoft Windows targets,
|
||
|
|
the compiler assumes that the
|
||
|
|
caller pops the stack for hidden pointer.
|
||
|
|
|
||
|
|
<br><dt><code>ms_hook_prologue</code><dd><a name="index-g_t_0040code_007bms_005fhook_005fprologue_007d-function-attribute_002c-x86-3170"></a>
|
||
|
|
On 32-bit and 64-bit x86 targets, you can use
|
||
|
|
this function attribute to make GCC generate the “hot-patching” function
|
||
|
|
prologue used in Win32 API functions in Microsoft Windows XP Service Pack 2
|
||
|
|
and newer.
|
||
|
|
|
||
|
|
<br><dt><code>hotpatch (</code><var>halfwords-before-function-label</var><code>,</code><var>halfwords-after-function-label</var><code>)</code><dd><a name="index-g_t_0040code_007bhotpatch_007d-function-attribute_002c-S_002f390-3171"></a>
|
||
|
|
On S/390 System z targets, you can use this function attribute to
|
||
|
|
make GCC generate a “hot-patching” function prologue. If the
|
||
|
|
<samp><span class="option">-mhotpatch=</span></samp> command-line option is used at the same time,
|
||
|
|
the <code>hotpatch</code> attribute takes precedence. The first of the
|
||
|
|
two arguments specifies the number of halfwords to be added before
|
||
|
|
the function label. A second argument can be used to specify the
|
||
|
|
number of halfwords to be added after the function label. For
|
||
|
|
both arguments the maximum allowed value is 1000000.
|
||
|
|
|
||
|
|
<p>If both arguments are zero, hotpatching is disabled.
|
||
|
|
|
||
|
|
<br><dt><code>naked</code><dd><a name="index-g_t_0040code_007bnaked_007d-function-attribute_002c-ARM-3172"></a><a name="index-g_t_0040code_007bnaked_007d-function-attribute_002c-AVR-3173"></a><a name="index-g_t_0040code_007bnaked_007d-function-attribute_002c-MCORE-3174"></a><a name="index-g_t_0040code_007bnaked_007d-function-attribute_002c-MSP430-3175"></a><a name="index-g_t_0040code_007bnaked_007d-function-attribute_002c-NDS32-3176"></a><a name="index-g_t_0040code_007bnaked_007d-function-attribute_002c-RL78-3177"></a><a name="index-g_t_0040code_007bnaked_007d-function-attribute_002c-RX-3178"></a><a name="index-g_t_0040code_007bnaked_007d-function-attribute_002c-SPU-3179"></a><a name="index-function-without-prologue_002fepilogue-code-3180"></a>This attribute is available on the ARM, AVR, MCORE, MSP430, NDS32,
|
||
|
|
RL78, RX and SPU ports. It allows the compiler to construct the
|
||
|
|
requisite function declaration, while allowing the body of the
|
||
|
|
function to be assembly code. The specified function will not have
|
||
|
|
prologue/epilogue sequences generated by the compiler. Only basic
|
||
|
|
<code>asm</code> statements can safely be included in naked functions
|
||
|
|
(see <a href="Basic-Asm.html#Basic-Asm">Basic Asm</a>). While using extended <code>asm</code> or a mixture of
|
||
|
|
basic <code>asm</code> and C code may appear to work, they cannot be
|
||
|
|
depended upon to work reliably and are not supported.
|
||
|
|
|
||
|
|
<br><dt><code>near</code><dd><a name="index-g_t_0040code_007bnear_007d-function-attribute_002c-MeP-3181"></a><a name="index-functions-that-do-not-handle-memory-bank-switching-on-68HC11_002f68HC12-3182"></a>On MeP targets this attribute causes the compiler to assume the called
|
||
|
|
function is close enough to use the normal calling convention,
|
||
|
|
overriding the <samp><span class="option">-mtf</span></samp> command-line option.
|
||
|
|
|
||
|
|
<br><dt><code>nesting</code><dd><a name="index-g_t_0040code_007bnesting_007d-function-attribute_002c-Blackfin-3183"></a><a name="index-Allow-nesting-in-an-interrupt-handler-on-the-Blackfin-processor-3184"></a>Use this attribute together with <code>interrupt_handler</code>,
|
||
|
|
<code>exception_handler</code> or <code>nmi_handler</code> to indicate that the function
|
||
|
|
entry code should enable nested interrupts or exceptions.
|
||
|
|
|
||
|
|
<br><dt><code>nmi_handler</code><dd><a name="index-g_t_0040code_007bnmi_005fhandler_007d-function-attribute_002c-Blackfin-3185"></a><a name="index-NMI-handler-functions-on-the-Blackfin-processor-3186"></a>Use this attribute on the Blackfin to indicate that the specified function
|
||
|
|
is an NMI handler. The compiler generates function entry and
|
||
|
|
exit sequences suitable for use in an NMI handler when this
|
||
|
|
attribute is present.
|
||
|
|
|
||
|
|
<br><dt><code>nocompression</code><dd><a name="index-g_t_0040code_007bnocompression_007d-function-attribute_002c-MIPS-3187"></a>On MIPS targets, you can use the <code>nocompression</code> function attribute
|
||
|
|
to locally turn off MIPS16 and microMIPS code generation. This attribute
|
||
|
|
overrides the <samp><span class="option">-mips16</span></samp> and <samp><span class="option">-mmicromips</span></samp> options on the
|
||
|
|
command line (see <a href="MIPS-Options.html#MIPS-Options">MIPS Options</a>).
|
||
|
|
|
||
|
|
<br><dt><code>no_instrument_function</code><dd><a name="index-g_t_0040code_007bno_005finstrument_005ffunction_007d-function-attribute-3188"></a><a name="index-finstrument_002dfunctions-3189"></a>If <samp><span class="option">-finstrument-functions</span></samp> is given, profiling function calls are
|
||
|
|
generated at entry and exit of most user-compiled functions.
|
||
|
|
Functions with this attribute are not so instrumented.
|
||
|
|
|
||
|
|
<br><dt><code>no_split_stack</code><dd><a name="index-g_t_0040code_007bno_005fsplit_005fstack_007d-function-attribute-3190"></a><a name="index-fsplit_002dstack-3191"></a>If <samp><span class="option">-fsplit-stack</span></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.
|
||
|
|
|
||
|
|
<br><dt><code>stack_protect</code><dd><a name="index-g_t_0040code_007bstack_005fprotect_007d-function-attribute-3192"></a>This function attribute make a stack protection of the function if
|
||
|
|
flags <samp><span class="option">fstack-protector</span></samp> or <samp><span class="option">fstack-protector-strong</span></samp>
|
||
|
|
or <samp><span class="option">fstack-protector-explicit</span></samp> are set.
|
||
|
|
|
||
|
|
<br><dt><code>noinline</code><dd><a name="index-g_t_0040code_007bnoinline_007d-function-attribute-3193"></a>This function attribute prevents a function from being considered for
|
||
|
|
inlining.
|
||
|
|
<!-- Don't enumerate the optimizations by name here; we try to be -->
|
||
|
|
<!-- future-compatible with this mechanism. -->
|
||
|
|
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
|
||
|
|
<pre class="smallexample"> asm ("");
|
||
|
|
</pre>
|
||
|
|
<p class="noindent">(see <a href="Extended-Asm.html#Extended-Asm">Extended Asm</a>) in the called function, to serve as a special
|
||
|
|
side-effect.
|
||
|
|
|
||
|
|
<br><dt><code>noclone</code><dd><a name="index-g_t_0040code_007bnoclone_007d-function-attribute-3194"></a>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.
|
||
|
|
|
||
|
|
<br><dt><code>no_icf</code><dd><a name="index-g_t_0040code_007bno_005ficf_007d-function-attribute-3195"></a>This function attribute prevents a functions from being merged with another
|
||
|
|
semantically equivalent function.
|
||
|
|
|
||
|
|
<br><dt><code>nonnull (</code><var>arg-index</var><code>, ...)</code><dd><a name="index-g_t_0040code_007bnonnull_007d-function-attribute-3196"></a>The <code>nonnull</code> attribute specifies that some function parameters should
|
||
|
|
be non-null pointers. For instance, the declaration:
|
||
|
|
|
||
|
|
<pre class="smallexample"> extern void *
|
||
|
|
my_memcpy (void *dest, const void *src, size_t len)
|
||
|
|
__attribute__((nonnull (1, 2)));
|
||
|
|
</pre>
|
||
|
|
<p class="noindent">causes the compiler to check that, in calls to <code>my_memcpy</code>,
|
||
|
|
arguments <var>dest</var> and <var>src</var> are non-null. If the compiler
|
||
|
|
determines that a null pointer is passed in an argument slot marked
|
||
|
|
as non-null, and the <samp><span class="option">-Wnonnull</span></samp> option is enabled, a warning
|
||
|
|
is issued. The compiler may also choose to make optimizations based
|
||
|
|
on the knowledge that certain function arguments will never be null.
|
||
|
|
|
||
|
|
<p>If no argument index list 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:
|
||
|
|
|
||
|
|
<pre class="smallexample"> extern void *
|
||
|
|
my_memcpy (void *dest, const void *src, size_t len)
|
||
|
|
__attribute__((nonnull));
|
||
|
|
</pre>
|
||
|
|
<br><dt><code>no_reorder</code><dd><a name="index-g_t_0040code_007bno_005freorder_007d-function-attribute-3197"></a>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><span class="option">-fno-toplevel-reorder</span></samp> option, but only applies to the
|
||
|
|
marked symbols.
|
||
|
|
|
||
|
|
<br><dt><code>returns_nonnull</code><dd><a name="index-g_t_0040code_007breturns_005fnonnull_007d-function-attribute-3198"></a>The <code>returns_nonnull</code> attribute specifies that the function
|
||
|
|
return value should be a non-null pointer. For instance, the declaration:
|
||
|
|
|
||
|
|
<pre class="smallexample"> extern void *
|
||
|
|
mymalloc (size_t len) __attribute__((returns_nonnull));
|
||
|
|
</pre>
|
||
|
|
<p class="noindent">lets the compiler optimize callers based on the knowledge
|
||
|
|
that the return value will never be null.
|
||
|
|
|
||
|
|
<br><dt><code>noreturn</code><dd><a name="index-g_t_0040code_007bnoreturn_007d-function-attribute-3199"></a>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,
|
||
|
|
|
||
|
|
<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>
|
||
|
|
<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>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>Do not assume that registers saved by the calling function are
|
||
|
|
restored before calling the <code>noreturn</code> function.
|
||
|
|
|
||
|
|
<p>It does not make sense for a <code>noreturn</code> function to have a return
|
||
|
|
type other than <code>void</code>.
|
||
|
|
|
||
|
|
<br><dt><code>nothrow</code><dd><a name="index-g_t_0040code_007bnothrow_007d-function-attribute-3200"></a>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.
|
||
|
|
|
||
|
|
<br><dt><code>nosave_low_regs</code><dd><a name="index-g_t_0040code_007bnosave_005flow_005fregs_007d-function-attribute_002c-SH-3201"></a>Use this attribute on SH targets to indicate that an <code>interrupt_handler</code>
|
||
|
|
function should not save and restore registers R0..R7. This can be used on SH3*
|
||
|
|
and SH4* targets that have a second R0..R7 register bank for non-reentrant
|
||
|
|
interrupt handlers.
|
||
|
|
|
||
|
|
<br><dt><code>optimize</code><dd><a name="index-g_t_0040code_007boptimize_007d-function-attribute-3202"></a>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. Arguments can either be numbers or strings. Numbers
|
||
|
|
are assumed to be an optimization level. Strings that begin with
|
||
|
|
<code>O</code> are assumed to be an optimization option, while other options
|
||
|
|
are assumed to be used with a <code>-f</code> prefix. You can also use the
|
||
|
|
‘<samp><span class="samp">#pragma GCC optimize</span></samp>’ pragma to set the optimization options
|
||
|
|
that affect 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
|
||
|
|
‘<samp><span class="samp">#pragma GCC optimize</span></samp>’ pragma.
|
||
|
|
|
||
|
|
<p>This can be used for instance to have frequently-executed functions
|
||
|
|
compiled with more aggressive optimization options that produce faster
|
||
|
|
and larger code, while other functions can be compiled with less
|
||
|
|
aggressive options.
|
||
|
|
|
||
|
|
<br><dt><code>OS_main</code><dt><code>OS_task</code><dd><a name="index-g_t_0040code_007bOS_005fmain_007d-function-attribute_002c-AVR-3203"></a><a name="index-g_t_0040code_007bOS_005ftask_007d-function-attribute_002c-AVR-3204"></a>On AVR, functions with the <code>OS_main</code> or <code>OS_task</code> attribute
|
||
|
|
do not save/restore any call-saved register in their prologue/epilogue.
|
||
|
|
|
||
|
|
<p>The <code>OS_main</code> attribute can be used when there <em>is
|
||
|
|
guarantee</em> that interrupts are disabled at the time when the function
|
||
|
|
is entered. This saves resources when the stack pointer has to be
|
||
|
|
changed to set up a frame for local variables.
|
||
|
|
|
||
|
|
<p>The <code>OS_task</code> attribute can be used when there is <em>no
|
||
|
|
guarantee</em> that interrupts are disabled at that time when the function
|
||
|
|
is entered like for, e.g. task functions in a multi-threading operating
|
||
|
|
system. In that case, changing the stack pointer register is
|
||
|
|
guarded by save/clear/restore of the global interrupt enable flag.
|
||
|
|
|
||
|
|
<p>The differences to the <code>naked</code> function attribute are:
|
||
|
|
<ul>
|
||
|
|
<li><code>naked</code> functions do not have a return instruction whereas
|
||
|
|
<code>OS_main</code> and <code>OS_task</code> functions have a <code>RET</code> or
|
||
|
|
<code>RETI</code> return instruction.
|
||
|
|
<li><code>naked</code> functions do not set up a frame for local variables
|
||
|
|
or a frame pointer whereas <code>OS_main</code> and <code>OS_task</code> do this
|
||
|
|
as needed.
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<br><dt><code>pcs</code><dd><a name="index-g_t_0040code_007bpcs_007d-function-attribute_002c-ARM-3205"></a>
|
||
|
|
The <code>pcs</code> attribute can be used to control the calling convention
|
||
|
|
used for a function on ARM. The attribute takes an argument that specifies
|
||
|
|
the calling convention to use.
|
||
|
|
|
||
|
|
<p>When compiling using the AAPCS ABI (or a variant of it) then valid
|
||
|
|
values for the argument are <code>"aapcs"</code> and <code>"aapcs-vfp"</code>. In
|
||
|
|
order to use a variant other than <code>"aapcs"</code> then the compiler must
|
||
|
|
be permitted to use the appropriate co-processor registers (i.e., the
|
||
|
|
VFP registers must be available in order to use <code>"aapcs-vfp"</code>).
|
||
|
|
For example,
|
||
|
|
|
||
|
|
<pre class="smallexample"> /* Argument passed in r0, and result returned in r0+r1. */
|
||
|
|
double f2d (float) __attribute__((pcs("aapcs")));
|
||
|
|
</pre>
|
||
|
|
<p>Variadic functions always use the <code>"aapcs"</code> calling convention and
|
||
|
|
the compiler rejects attempts to specify an alternative.
|
||
|
|
|
||
|
|
<br><dt><code>pure</code><dd><a name="index-g_t_0040code_007bpure_007d-function-attribute-3206"></a>Many functions have no effects except the return value and their
|
||
|
|
return value depends only on the parameters and/or global variables.
|
||
|
|
Such a function can be subject
|
||
|
|
to common subexpression elimination and loop optimization just as an
|
||
|
|
arithmetic operator would be. These functions should be declared
|
||
|
|
with the attribute <code>pure</code>. For example,
|
||
|
|
|
||
|
|
<pre class="smallexample"> int square (int) __attribute__ ((pure));
|
||
|
|
</pre>
|
||
|
|
<p class="noindent">says that the hypothetical function <code>square</code> is safe to call
|
||
|
|
fewer times than the program says.
|
||
|
|
|
||
|
|
<p>Some of 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
|
||
|
|
two consecutive calls (such as <code>feof</code> in a multithreading environment).
|
||
|
|
|
||
|
|
<br><dt><code>hot</code><dd><a name="index-g_t_0040code_007bhot_007d-function-attribute-3207"></a>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>When profile feedback is available, via <samp><span class="option">-fprofile-use</span></samp>, hot functions
|
||
|
|
are automatically detected and this attribute is ignored.
|
||
|
|
|
||
|
|
<br><dt><code>cold</code><dd><a name="index-g_t_0040code_007bcold_007d-function-attribute-3208"></a>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>When profile feedback is available, via <samp><span class="option">-fprofile-use</span></samp>, cold functions
|
||
|
|
are automatically detected and this attribute is ignored.
|
||
|
|
|
||
|
|
<br><dt><code>no_sanitize_address</code><dt><code>no_address_safety_analysis</code><dd><a name="index-g_t_0040code_007bno_005fsanitize_005faddress_007d-function-attribute-3209"></a>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><span class="option">-fsanitize=address</span></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>.
|
||
|
|
|
||
|
|
<br><dt><code>no_sanitize_thread</code><dd><a name="index-g_t_0040code_007bno_005fsanitize_005fthread_007d-function-attribute-3210"></a>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><span class="option">-fsanitize=thread</span></samp> option.
|
||
|
|
|
||
|
|
<br><dt><code>no_sanitize_undefined</code><dd><a name="index-g_t_0040code_007bno_005fsanitize_005fundefined_007d-function-attribute-3211"></a>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><span class="option">-fsanitize=undefined</span></samp> option.
|
||
|
|
|
||
|
|
<br><dt><code>bnd_legacy</code><dd><a name="index-g_t_0040code_007bbnd_005flegacy_007d-function-attribute-3212"></a><a name="index-Pointer-Bounds-Checker-attributes-3213"></a>The <code>bnd_legacy</code> attribute on functions is used to inform the
|
||
|
|
compiler that the function should not be instrumented when compiled
|
||
|
|
with the <samp><span class="option">-fcheck-pointer-bounds</span></samp> option.
|
||
|
|
|
||
|
|
<br><dt><code>bnd_instrument</code><dd><a name="index-g_t_0040code_007bbnd_005finstrument_007d-function-attribute-3214"></a>The <code>bnd_instrument</code> attribute on functions is used to inform the
|
||
|
|
compiler that the function should be instrumented when compiled
|
||
|
|
with the <samp><span class="option">-fchkp-instrument-marked-only</span></samp> option.
|
||
|
|
|
||
|
|
<br><dt><code>regparm (</code><var>number</var><code>)</code><dd><a name="index-g_t_0040code_007bregparm_007d-function-attribute_002c-x86-3215"></a><a name="index-functions-that-are-passed-arguments-in-registers-on-x86_002d32-3216"></a>On x86-32 targets, the <code>regparm</code> attribute causes the compiler to
|
||
|
|
pass arguments number one to <var>number</var> if they are of integral type
|
||
|
|
in registers EAX, EDX, and ECX instead of on the stack. Functions that
|
||
|
|
take a variable number of arguments continue to be passed all of their
|
||
|
|
arguments on the stack.
|
||
|
|
|
||
|
|
<p>Beware that on some ELF systems this attribute is unsuitable for
|
||
|
|
global functions in shared libraries with lazy binding (which is the
|
||
|
|
default). Lazy binding sends the first call via resolving code in
|
||
|
|
the loader, which might assume EAX, EDX and ECX can be clobbered, as
|
||
|
|
per the standard calling conventions. Solaris 8 is affected by this.
|
||
|
|
Systems with the GNU C Library version 2.1 or higher
|
||
|
|
and FreeBSD are believed to be
|
||
|
|
safe since the loaders there save EAX, EDX and ECX. (Lazy binding can be
|
||
|
|
disabled with the linker or the loader if desired, to avoid the
|
||
|
|
problem.)
|
||
|
|
|
||
|
|
<br><dt><code>reset</code><dd><a name="index-g_t_0040code_007breset_007d-function-attribute_002c-NDS32-3217"></a><a name="index-reset-handler-functions-3218"></a>Use this attribute on the NDS32 target to indicate that the specified function
|
||
|
|
is a reset handler. The compiler will generate corresponding sections
|
||
|
|
for use in a reset handler. You can use the following attributes
|
||
|
|
to provide extra exception handling:
|
||
|
|
<dl>
|
||
|
|
<dt><code>nmi</code><dd><a name="index-g_t_0040code_007bnmi_007d-function-attribute_002c-NDS32-3219"></a>Provide a user-defined function to handle NMI exception.
|
||
|
|
<br><dt><code>warm</code><dd><a name="index-g_t_0040code_007bwarm_007d-function-attribute_002c-NDS32-3220"></a>Provide a user-defined function to handle warm reset exception.
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<br><dt><code>sseregparm</code><dd><a name="index-g_t_0040code_007bsseregparm_007d-function-attribute_002c-x86-3221"></a>On x86-32 targets with SSE support, the <code>sseregparm</code> attribute
|
||
|
|
causes the compiler to pass up to 3 floating-point arguments in
|
||
|
|
SSE registers instead of on the stack. Functions that take a
|
||
|
|
variable number of arguments continue to pass all of their
|
||
|
|
floating-point arguments on the stack.
|
||
|
|
|
||
|
|
<br><dt><code>force_align_arg_pointer</code><dd><a name="index-g_t_0040code_007bforce_005falign_005farg_005fpointer_007d-function-attribute_002c-x86-3222"></a>On x86 targets, the <code>force_align_arg_pointer</code> attribute may be
|
||
|
|
applied to individual function definitions, generating an alternate
|
||
|
|
prologue and epilogue that realigns the run-time stack if necessary.
|
||
|
|
This supports mixing legacy codes that run with a 4-byte aligned stack
|
||
|
|
with modern codes that keep a 16-byte stack for SSE compatibility.
|
||
|
|
|
||
|
|
<br><dt><code>renesas</code><dd><a name="index-g_t_0040code_007brenesas_007d-function-attribute_002c-SH-3223"></a>On SH targets this attribute specifies that the function or struct follows the
|
||
|
|
Renesas ABI.
|
||
|
|
|
||
|
|
<br><dt><code>resbank</code><dd><a name="index-g_t_0040code_007bresbank_007d-function-attribute_002c-SH-3224"></a>On the SH2A target, this attribute enables the high-speed register
|
||
|
|
saving and restoration using a register bank for <code>interrupt_handler</code>
|
||
|
|
routines. Saving to the bank is performed automatically after the CPU
|
||
|
|
accepts an interrupt that uses a register bank.
|
||
|
|
|
||
|
|
<p>The nineteen 32-bit registers comprising general register R0 to R14,
|
||
|
|
control register GBR, and system registers MACH, MACL, and PR and the
|
||
|
|
vector table address offset are saved into a register bank. Register
|
||
|
|
banks are stacked in first-in last-out (FILO) sequence. Restoration
|
||
|
|
from the bank is executed by issuing a RESBANK instruction.
|
||
|
|
|
||
|
|
<br><dt><code>returns_twice</code><dd><a name="index-g_t_0040code_007breturns_005ftwice_007d-function-attribute-3225"></a>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.
|
||
|
|
|
||
|
|
<br><dt><code>saveall</code><dd><a name="index-g_t_0040code_007bsaveall_007d-function-attribute_002c-Blackfin-3226"></a><a name="index-g_t_0040code_007bsaveall_007d-function-attribute_002c-H8_002f300-3227"></a><a name="index-save-all-registers-on-the-Blackfin_002c-H8_002f300_002c-H8_002f300H_002c-and-H8S-3228"></a>Use this attribute on the Blackfin, H8/300, H8/300H, and H8S to indicate that
|
||
|
|
all registers except the stack pointer should be saved in the prologue
|
||
|
|
regardless of whether they are used or not.
|
||
|
|
|
||
|
|
<br><dt><code>save_volatiles</code><dd><a name="index-g_t_0040code_007bsave_005fvolatiles_007d-function-attribute_002c-MicroBlaze-3229"></a>Use this attribute on the MicroBlaze to indicate that the function is
|
||
|
|
an interrupt handler. All volatile registers (in addition to non-volatile
|
||
|
|
registers) are saved in the function prologue. If the function is a leaf
|
||
|
|
function, only volatiles used by the function are saved. A normal function
|
||
|
|
return is generated instead of a return from interrupt.
|
||
|
|
|
||
|
|
<br><dt><code>break_handler</code><dd><a name="index-g_t_0040code_007bbreak_005fhandler_007d-function-attribute_002c-MicroBlaze-3230"></a><a name="index-break-handler-functions-3231"></a>Use this attribute on the MicroBlaze ports to indicate that
|
||
|
|
the specified function is a break handler. The compiler generates function
|
||
|
|
entry and exit sequences suitable for use in an break handler when this
|
||
|
|
attribute is present. The return from <code>break_handler</code> is done through
|
||
|
|
the <code>rtbd</code> instead of <code>rtsd</code>.
|
||
|
|
|
||
|
|
<pre class="smallexample"> void f () __attribute__ ((break_handler));
|
||
|
|
</pre>
|
||
|
|
<br><dt><code>section ("</code><var>section-name</var><code>")</code><dd><a name="index-g_t_0040code_007bsection_007d-function-attribute-3232"></a>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:
|
||
|
|
|
||
|
|
<pre class="smallexample"> extern void foobar (void) __attribute__ ((section ("bar")));
|
||
|
|
</pre>
|
||
|
|
<p class="noindent">puts the function <code>foobar</code> in the <code>bar</code> section.
|
||
|
|
|
||
|
|
<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.
|
||
|
|
|
||
|
|
<br><dt><code>sentinel</code><dd><a name="index-g_t_0040code_007bsentinel_007d-function-attribute-3233"></a>This function attribute ensures that a parameter in a function call is
|
||
|
|
an explicit <code>NULL</code>. The attribute is only valid on variadic
|
||
|
|
functions. By default, the sentinel is located at position zero, the
|
||
|
|
last parameter of the function call. If an optional integer position
|
||
|
|
argument P is supplied to the attribute, the sentinel must be located at
|
||
|
|
position P counting backwards from the end of the argument list.
|
||
|
|
|
||
|
|
<pre class="smallexample"> __attribute__ ((sentinel))
|
||
|
|
is equivalent to
|
||
|
|
__attribute__ ((sentinel(0)))
|
||
|
|
</pre>
|
||
|
|
<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>A valid <code>NULL</code> in this context is defined as zero with any pointer
|
||
|
|
type. If your system defines the <code>NULL</code> macro with an integer type
|
||
|
|
then you need to add an explicit cast. GCC replaces <code>stddef.h</code>
|
||
|
|
with a copy that redefines NULL appropriately.
|
||
|
|
|
||
|
|
<p>The warnings for missing or incorrect sentinels are enabled with
|
||
|
|
<samp><span class="option">-Wformat</span></samp>.
|
||
|
|
|
||
|
|
<br><dt><code>short_call</code><dd>See <code>long_call</code>.
|
||
|
|
|
||
|
|
<br><dt><code>shortcall</code><dd>See <code>longcall</code>.
|
||
|
|
|
||
|
|
<br><dt><code>signal</code><dd><a name="index-g_t_0040code_007bsignal_007d-function-attribute_002c-AVR-3234"></a>Use this attribute on the AVR to indicate that the specified
|
||
|
|
function is an interrupt handler. The compiler generates function
|
||
|
|
entry and exit sequences suitable for use in an interrupt handler when this
|
||
|
|
attribute is present.
|
||
|
|
|
||
|
|
<p>See also the <code>interrupt</code> function attribute.
|
||
|
|
|
||
|
|
<p>The AVR hardware globally disables interrupts when an interrupt is executed.
|
||
|
|
Interrupt handler functions defined with the <code>signal</code> attribute
|
||
|
|
do not re-enable interrupts. It is save to enable interrupts in a
|
||
|
|
<code>signal</code> handler. This “save” only applies to the code
|
||
|
|
generated by the compiler and not to the IRQ layout of the
|
||
|
|
application which is responsibility of the application.
|
||
|
|
|
||
|
|
<p>If both <code>signal</code> and <code>interrupt</code> are specified for the same
|
||
|
|
function, <code>signal</code> is silently ignored.
|
||
|
|
|
||
|
|
<br><dt><code>sp_switch</code><dd><a name="index-g_t_0040code_007bsp_005fswitch_007d-function-attribute_002c-SH-3235"></a>Use this attribute on the SH to indicate an <code>interrupt_handler</code>
|
||
|
|
function should switch to an alternate stack. It expects a string
|
||
|
|
argument that names a global variable holding the address of the
|
||
|
|
alternate stack.
|
||
|
|
|
||
|
|
<pre class="smallexample"> void *alt_stack;
|
||
|
|
void f () __attribute__ ((interrupt_handler,
|
||
|
|
sp_switch ("alt_stack")));
|
||
|
|
</pre>
|
||
|
|
<br><dt><code>stdcall</code><dd><a name="index-g_t_0040code_007bstdcall_007d-function-attribute_002c-x86_002d32-3236"></a><a name="index-functions-that-pop-the-argument-stack-on-x86_002d32-3237"></a>On x86-32 targets, the <code>stdcall</code> attribute causes the compiler to
|
||
|
|
assume that the called function pops off the stack space used to
|
||
|
|
pass arguments, unless it takes a variable number of arguments.
|
||
|
|
|
||
|
|
<br><dt><code>syscall_linkage</code><dd><a name="index-g_t_0040code_007bsyscall_005flinkage_007d-function-attribute_002c-IA_002d64-3238"></a>This attribute is used to modify the IA-64 calling convention by marking
|
||
|
|
all input registers as live at all function exits. This makes it possible
|
||
|
|
to restart a system call after an interrupt without having to save/restore
|
||
|
|
the input registers. This also prevents kernel data from leaking into
|
||
|
|
application code.
|
||
|
|
|
||
|
|
<br><dt><code>target</code><dd><a name="index-g_t_0040code_007btarget_007d-function-attribute-3239"></a>The <code>target</code> attribute is used to specify that a function is to
|
||
|
|
be compiled with different target options than specified on the
|
||
|
|
command line. This can be used for instance to have functions
|
||
|
|
compiled with a different ISA (instruction set architecture) than the
|
||
|
|
default. You can also use the ‘<samp><span class="samp">#pragma GCC target</span></samp>’ pragma to set
|
||
|
|
more than one function to be compiled with specific target options.
|
||
|
|
See <a href="Function-Specific-Option-Pragmas.html#Function-Specific-Option-Pragmas">Function Specific Option Pragmas</a>, for details about the
|
||
|
|
‘<samp><span class="samp">#pragma GCC target</span></samp>’ pragma.
|
||
|
|
|
||
|
|
<p>For instance on an x86, you could compile one function with
|
||
|
|
<code>target("sse4.1,arch=core2")</code> and another with
|
||
|
|
<code>target("sse4a,arch=amdfam10")</code>. This is equivalent to
|
||
|
|
compiling the first function with <samp><span class="option">-msse4.1</span></samp> and
|
||
|
|
<samp><span class="option">-march=core2</span></samp> options, and the second function with
|
||
|
|
<samp><span class="option">-msse4a</span></samp> and <samp><span class="option">-march=amdfam10</span></samp> options. It is up to the
|
||
|
|
user 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).
|
||
|
|
|
||
|
|
<pre class="smallexample"> int core2_func (void) __attribute__ ((__target__ ("arch=core2")));
|
||
|
|
int sse3_func (void) __attribute__ ((__target__ ("sse3")));
|
||
|
|
</pre>
|
||
|
|
<p>You can either use multiple
|
||
|
|
strings to specify multiple options, or separate the options
|
||
|
|
with a comma (‘<samp><span class="samp">,</span></samp>’).
|
||
|
|
|
||
|
|
<p>The <code>target</code> attribute is presently implemented for
|
||
|
|
x86, PowerPC, and Nios II targets only.
|
||
|
|
The options supported are specific to each target.
|
||
|
|
|
||
|
|
<p>On the x86, the following options are allowed:
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt>‘<samp><span class="samp">abm</span></samp>’<dt>‘<samp><span class="samp">no-abm</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022abm_0022_0029_007d-function-attribute_002c-x86-3240"></a>Enable/disable the generation of the advanced bit instructions.
|
||
|
|
|
||
|
|
<br><dt>‘<samp><span class="samp">aes</span></samp>’<dt>‘<samp><span class="samp">no-aes</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022aes_0022_0029_007d-function-attribute_002c-x86-3241"></a>Enable/disable the generation of the AES instructions.
|
||
|
|
|
||
|
|
<br><dt>‘<samp><span class="samp">default</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022default_0022_0029_007d-function-attribute_002c-x86-3242"></a>See <a href="Function-Multiversioning.html#Function-Multiversioning">Function Multiversioning</a>, where it is used to specify the
|
||
|
|
default function version.
|
||
|
|
|
||
|
|
<br><dt>‘<samp><span class="samp">mmx</span></samp>’<dt>‘<samp><span class="samp">no-mmx</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022mmx_0022_0029_007d-function-attribute_002c-x86-3243"></a>Enable/disable the generation of the MMX instructions.
|
||
|
|
|
||
|
|
<br><dt>‘<samp><span class="samp">pclmul</span></samp>’<dt>‘<samp><span class="samp">no-pclmul</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022pclmul_0022_0029_007d-function-attribute_002c-x86-3244"></a>Enable/disable the generation of the PCLMUL instructions.
|
||
|
|
|
||
|
|
<br><dt>‘<samp><span class="samp">popcnt</span></samp>’<dt>‘<samp><span class="samp">no-popcnt</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022popcnt_0022_0029_007d-function-attribute_002c-x86-3245"></a>Enable/disable the generation of the POPCNT instruction.
|
||
|
|
|
||
|
|
<br><dt>‘<samp><span class="samp">sse</span></samp>’<dt>‘<samp><span class="samp">no-sse</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022sse_0022_0029_007d-function-attribute_002c-x86-3246"></a>Enable/disable the generation of the SSE instructions.
|
||
|
|
|
||
|
|
<br><dt>‘<samp><span class="samp">sse2</span></samp>’<dt>‘<samp><span class="samp">no-sse2</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022sse2_0022_0029_007d-function-attribute_002c-x86-3247"></a>Enable/disable the generation of the SSE2 instructions.
|
||
|
|
|
||
|
|
<br><dt>‘<samp><span class="samp">sse3</span></samp>’<dt>‘<samp><span class="samp">no-sse3</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022sse3_0022_0029_007d-function-attribute_002c-x86-3248"></a>Enable/disable the generation of the SSE3 instructions.
|
||
|
|
|
||
|
|
<br><dt>‘<samp><span class="samp">sse4</span></samp>’<dt>‘<samp><span class="samp">no-sse4</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022sse4_0022_0029_007d-function-attribute_002c-x86-3249"></a>Enable/disable the generation of the SSE4 instructions (both SSE4.1
|
||
|
|
and SSE4.2).
|
||
|
|
|
||
|
|
<br><dt>‘<samp><span class="samp">sse4.1</span></samp>’<dt>‘<samp><span class="samp">no-sse4.1</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022sse4_002e1_0022_0029_007d-function-attribute_002c-x86-3250"></a>Enable/disable the generation of the sse4.1 instructions.
|
||
|
|
|
||
|
|
<br><dt>‘<samp><span class="samp">sse4.2</span></samp>’<dt>‘<samp><span class="samp">no-sse4.2</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022sse4_002e2_0022_0029_007d-function-attribute_002c-x86-3251"></a>Enable/disable the generation of the sse4.2 instructions.
|
||
|
|
|
||
|
|
<br><dt>‘<samp><span class="samp">sse4a</span></samp>’<dt>‘<samp><span class="samp">no-sse4a</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022sse4a_0022_0029_007d-function-attribute_002c-x86-3252"></a>Enable/disable the generation of the SSE4A instructions.
|
||
|
|
|
||
|
|
<br><dt>‘<samp><span class="samp">fma4</span></samp>’<dt>‘<samp><span class="samp">no-fma4</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022fma4_0022_0029_007d-function-attribute_002c-x86-3253"></a>Enable/disable the generation of the FMA4 instructions.
|
||
|
|
|
||
|
|
<br><dt>‘<samp><span class="samp">xop</span></samp>’<dt>‘<samp><span class="samp">no-xop</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022xop_0022_0029_007d-function-attribute_002c-x86-3254"></a>Enable/disable the generation of the XOP instructions.
|
||
|
|
|
||
|
|
<br><dt>‘<samp><span class="samp">lwp</span></samp>’<dt>‘<samp><span class="samp">no-lwp</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022lwp_0022_0029_007d-function-attribute_002c-x86-3255"></a>Enable/disable the generation of the LWP instructions.
|
||
|
|
|
||
|
|
<br><dt>‘<samp><span class="samp">ssse3</span></samp>’<dt>‘<samp><span class="samp">no-ssse3</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022ssse3_0022_0029_007d-function-attribute_002c-x86-3256"></a>Enable/disable the generation of the SSSE3 instructions.
|
||
|
|
|
||
|
|
<br><dt>‘<samp><span class="samp">cld</span></samp>’<dt>‘<samp><span class="samp">no-cld</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022cld_0022_0029_007d-function-attribute_002c-x86-3257"></a>Enable/disable the generation of the CLD before string moves.
|
||
|
|
|
||
|
|
<br><dt>‘<samp><span class="samp">fancy-math-387</span></samp>’<dt>‘<samp><span class="samp">no-fancy-math-387</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022fancy_002dmath_002d387_0022_0029_007d-function-attribute_002c-x86-3258"></a>Enable/disable the generation of the <code>sin</code>, <code>cos</code>, and
|
||
|
|
<code>sqrt</code> instructions on the 387 floating-point unit.
|
||
|
|
|
||
|
|
<br><dt>‘<samp><span class="samp">fused-madd</span></samp>’<dt>‘<samp><span class="samp">no-fused-madd</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022fused_002dmadd_0022_0029_007d-function-attribute_002c-x86-3259"></a>Enable/disable the generation of the fused multiply/add instructions.
|
||
|
|
|
||
|
|
<br><dt>‘<samp><span class="samp">ieee-fp</span></samp>’<dt>‘<samp><span class="samp">no-ieee-fp</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022ieee_002dfp_0022_0029_007d-function-attribute_002c-x86-3260"></a>Enable/disable the generation of floating point that depends on IEEE arithmetic.
|
||
|
|
|
||
|
|
<br><dt>‘<samp><span class="samp">inline-all-stringops</span></samp>’<dt>‘<samp><span class="samp">no-inline-all-stringops</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022inline_002dall_002dstringops_0022_0029_007d-function-attribute_002c-x86-3261"></a>Enable/disable inlining of string operations.
|
||
|
|
|
||
|
|
<br><dt>‘<samp><span class="samp">inline-stringops-dynamically</span></samp>’<dt>‘<samp><span class="samp">no-inline-stringops-dynamically</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022inline_002dstringops_002ddynamically_0022_0029_007d-function-attribute_002c-x86-3262"></a>Enable/disable the generation of the inline code to do small string
|
||
|
|
operations and calling the library routines for large operations.
|
||
|
|
|
||
|
|
<br><dt>‘<samp><span class="samp">align-stringops</span></samp>’<dt>‘<samp><span class="samp">no-align-stringops</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022align_002dstringops_0022_0029_007d-function-attribute_002c-x86-3263"></a>Do/do not align destination of inlined string operations.
|
||
|
|
|
||
|
|
<br><dt>‘<samp><span class="samp">recip</span></samp>’<dt>‘<samp><span class="samp">no-recip</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022recip_0022_0029_007d-function-attribute_002c-x86-3264"></a>Enable/disable the generation of RCPSS, RCPPS, RSQRTSS and RSQRTPS
|
||
|
|
instructions followed an additional Newton-Raphson step instead of
|
||
|
|
doing a floating-point division.
|
||
|
|
|
||
|
|
<br><dt>‘<samp><span class="samp">arch=</span><var>ARCH</var></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022arch_003d_0040var_007bARCH_007d_0022_0029_007d-function-attribute_002c-x86-3265"></a>Specify the architecture to generate code for in compiling the function.
|
||
|
|
|
||
|
|
<br><dt>‘<samp><span class="samp">tune=</span><var>TUNE</var></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022tune_003d_0040var_007bTUNE_007d_0022_0029_007d-function-attribute_002c-x86-3266"></a>Specify the architecture to tune for in compiling the function.
|
||
|
|
|
||
|
|
<br><dt>‘<samp><span class="samp">fpmath=</span><var>FPMATH</var></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022fpmath_003d_0040var_007bFPMATH_007d_0022_0029_007d-function-attribute_002c-x86-3267"></a>Specify which floating-point unit to use. The
|
||
|
|
<code>target("fpmath=sse,387")</code> option must be specified as
|
||
|
|
<code>target("fpmath=sse+387")</code> because the comma would separate
|
||
|
|
different options.
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<p>On the PowerPC, the following options are allowed:
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt>‘<samp><span class="samp">altivec</span></samp>’<dt>‘<samp><span class="samp">no-altivec</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022altivec_0022_0029_007d-function-attribute_002c-PowerPC-3268"></a>Generate code that uses (does not use) AltiVec instructions. In
|
||
|
|
32-bit code, you cannot enable AltiVec instructions unless
|
||
|
|
<samp><span class="option">-mabi=altivec</span></samp> is used on the command line.
|
||
|
|
|
||
|
|
<br><dt>‘<samp><span class="samp">cmpb</span></samp>’<dt>‘<samp><span class="samp">no-cmpb</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022cmpb_0022_0029_007d-function-attribute_002c-PowerPC-3269"></a>Generate code that uses (does not use) the compare bytes instruction
|
||
|
|
implemented on the POWER6 processor and other processors that support
|
||
|
|
the PowerPC V2.05 architecture.
|
||
|
|
|
||
|
|
<br><dt>‘<samp><span class="samp">dlmzb</span></samp>’<dt>‘<samp><span class="samp">no-dlmzb</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022dlmzb_0022_0029_007d-function-attribute_002c-PowerPC-3270"></a>Generate code that uses (does not use) the string-search ‘<samp><span class="samp">dlmzb</span></samp>’
|
||
|
|
instruction on the IBM 405, 440, 464 and 476 processors. This instruction is
|
||
|
|
generated by default when targeting those processors.
|
||
|
|
|
||
|
|
<br><dt>‘<samp><span class="samp">fprnd</span></samp>’<dt>‘<samp><span class="samp">no-fprnd</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022fprnd_0022_0029_007d-function-attribute_002c-PowerPC-3271"></a>Generate code that uses (does not use) the FP round to integer
|
||
|
|
instructions implemented on the POWER5+ processor and other processors
|
||
|
|
that support the PowerPC V2.03 architecture.
|
||
|
|
|
||
|
|
<br><dt>‘<samp><span class="samp">hard-dfp</span></samp>’<dt>‘<samp><span class="samp">no-hard-dfp</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022hard_002ddfp_0022_0029_007d-function-attribute_002c-PowerPC-3272"></a>Generate code that uses (does not use) the decimal floating-point
|
||
|
|
instructions implemented on some POWER processors.
|
||
|
|
|
||
|
|
<br><dt>‘<samp><span class="samp">isel</span></samp>’<dt>‘<samp><span class="samp">no-isel</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022isel_0022_0029_007d-function-attribute_002c-PowerPC-3273"></a>Generate code that uses (does not use) ISEL instruction.
|
||
|
|
|
||
|
|
<br><dt>‘<samp><span class="samp">mfcrf</span></samp>’<dt>‘<samp><span class="samp">no-mfcrf</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022mfcrf_0022_0029_007d-function-attribute_002c-PowerPC-3274"></a>Generate code that uses (does not use) the move from condition
|
||
|
|
register field instruction implemented on the POWER4 processor and
|
||
|
|
other processors that support the PowerPC V2.01 architecture.
|
||
|
|
|
||
|
|
<br><dt>‘<samp><span class="samp">mfpgpr</span></samp>’<dt>‘<samp><span class="samp">no-mfpgpr</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022mfpgpr_0022_0029_007d-function-attribute_002c-PowerPC-3275"></a>Generate code that uses (does not use) the FP move to/from general
|
||
|
|
purpose register instructions implemented on the POWER6X processor and
|
||
|
|
other processors that support the extended PowerPC V2.05 architecture.
|
||
|
|
|
||
|
|
<br><dt>‘<samp><span class="samp">mulhw</span></samp>’<dt>‘<samp><span class="samp">no-mulhw</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022mulhw_0022_0029_007d-function-attribute_002c-PowerPC-3276"></a>Generate code that uses (does not use) the half-word multiply and
|
||
|
|
multiply-accumulate instructions on the IBM 405, 440, 464 and 476 processors.
|
||
|
|
These instructions are generated by default when targeting those
|
||
|
|
processors.
|
||
|
|
|
||
|
|
<br><dt>‘<samp><span class="samp">multiple</span></samp>’<dt>‘<samp><span class="samp">no-multiple</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022multiple_0022_0029_007d-function-attribute_002c-PowerPC-3277"></a>Generate code that uses (does not use) the load multiple word
|
||
|
|
instructions and the store multiple word instructions.
|
||
|
|
|
||
|
|
<br><dt>‘<samp><span class="samp">update</span></samp>’<dt>‘<samp><span class="samp">no-update</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022update_0022_0029_007d-function-attribute_002c-PowerPC-3278"></a>Generate code that uses (does not use) the load or store instructions
|
||
|
|
that update the base register to the address of the calculated memory
|
||
|
|
location.
|
||
|
|
|
||
|
|
<br><dt>‘<samp><span class="samp">popcntb</span></samp>’<dt>‘<samp><span class="samp">no-popcntb</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022popcntb_0022_0029_007d-function-attribute_002c-PowerPC-3279"></a>Generate code that uses (does not use) the popcount and double-precision
|
||
|
|
FP reciprocal estimate instruction implemented on the POWER5
|
||
|
|
processor and other processors that support the PowerPC V2.02
|
||
|
|
architecture.
|
||
|
|
|
||
|
|
<br><dt>‘<samp><span class="samp">popcntd</span></samp>’<dt>‘<samp><span class="samp">no-popcntd</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022popcntd_0022_0029_007d-function-attribute_002c-PowerPC-3280"></a>Generate code that uses (does not use) the popcount instruction
|
||
|
|
implemented on the POWER7 processor and other processors that support
|
||
|
|
the PowerPC V2.06 architecture.
|
||
|
|
|
||
|
|
<br><dt>‘<samp><span class="samp">powerpc-gfxopt</span></samp>’<dt>‘<samp><span class="samp">no-powerpc-gfxopt</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022powerpc_002dgfxopt_0022_0029_007d-function-attribute_002c-PowerPC-3281"></a>Generate code that uses (does not use) the optional PowerPC
|
||
|
|
architecture instructions in the Graphics group, including
|
||
|
|
floating-point select.
|
||
|
|
|
||
|
|
<br><dt>‘<samp><span class="samp">powerpc-gpopt</span></samp>’<dt>‘<samp><span class="samp">no-powerpc-gpopt</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022powerpc_002dgpopt_0022_0029_007d-function-attribute_002c-PowerPC-3282"></a>Generate code that uses (does not use) the optional PowerPC
|
||
|
|
architecture instructions in the General Purpose group, including
|
||
|
|
floating-point square root.
|
||
|
|
|
||
|
|
<br><dt>‘<samp><span class="samp">recip-precision</span></samp>’<dt>‘<samp><span class="samp">no-recip-precision</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022recip_002dprecision_0022_0029_007d-function-attribute_002c-PowerPC-3283"></a>Assume (do not assume) that the reciprocal estimate instructions
|
||
|
|
provide higher-precision estimates than is mandated by the PowerPC
|
||
|
|
ABI.
|
||
|
|
|
||
|
|
<br><dt>‘<samp><span class="samp">string</span></samp>’<dt>‘<samp><span class="samp">no-string</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022string_0022_0029_007d-function-attribute_002c-PowerPC-3284"></a>Generate code that uses (does not use) the load string instructions
|
||
|
|
and the store string word instructions to save multiple registers and
|
||
|
|
do small block moves.
|
||
|
|
|
||
|
|
<br><dt>‘<samp><span class="samp">vsx</span></samp>’<dt>‘<samp><span class="samp">no-vsx</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022vsx_0022_0029_007d-function-attribute_002c-PowerPC-3285"></a>Generate code that uses (does not use) vector/scalar (VSX)
|
||
|
|
instructions, and also enable the use of built-in functions that allow
|
||
|
|
more direct access to the VSX instruction set. In 32-bit code, you
|
||
|
|
cannot enable VSX or AltiVec instructions unless
|
||
|
|
<samp><span class="option">-mabi=altivec</span></samp> is used on the command line.
|
||
|
|
|
||
|
|
<br><dt>‘<samp><span class="samp">friz</span></samp>’<dt>‘<samp><span class="samp">no-friz</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022friz_0022_0029_007d-function-attribute_002c-PowerPC-3286"></a>Generate (do not generate) the <code>friz</code> instruction when the
|
||
|
|
<samp><span class="option">-funsafe-math-optimizations</span></samp> option is used to optimize
|
||
|
|
rounding a floating-point value to 64-bit integer and back to floating
|
||
|
|
point. The <code>friz</code> instruction does not return the same value if
|
||
|
|
the floating-point number is too large to fit in an integer.
|
||
|
|
|
||
|
|
<br><dt>‘<samp><span class="samp">avoid-indexed-addresses</span></samp>’<dt>‘<samp><span class="samp">no-avoid-indexed-addresses</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022avoid_002dindexed_002daddresses_0022_0029_007d-function-attribute_002c-PowerPC-3287"></a>Generate code that tries to avoid (not avoid) the use of indexed load
|
||
|
|
or store instructions.
|
||
|
|
|
||
|
|
<br><dt>‘<samp><span class="samp">paired</span></samp>’<dt>‘<samp><span class="samp">no-paired</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022paired_0022_0029_007d-function-attribute_002c-PowerPC-3288"></a>Generate code that uses (does not use) the generation of PAIRED simd
|
||
|
|
instructions.
|
||
|
|
|
||
|
|
<br><dt>‘<samp><span class="samp">longcall</span></samp>’<dt>‘<samp><span class="samp">no-longcall</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022longcall_0022_0029_007d-function-attribute_002c-PowerPC-3289"></a>Generate code that assumes (does not assume) that all calls are far
|
||
|
|
away so that a longer more expensive calling sequence is required.
|
||
|
|
|
||
|
|
<br><dt>‘<samp><span class="samp">cpu=</span><var>CPU</var></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022cpu_003d_0040var_007bCPU_007d_0022_0029_007d-function-attribute_002c-PowerPC-3290"></a>Specify the architecture to generate code for when compiling the
|
||
|
|
function. If you select the <code>target("cpu=power7")</code> attribute when
|
||
|
|
generating 32-bit code, VSX and AltiVec instructions are not generated
|
||
|
|
unless you use the <samp><span class="option">-mabi=altivec</span></samp> option on the command line.
|
||
|
|
|
||
|
|
<br><dt>‘<samp><span class="samp">tune=</span><var>TUNE</var></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022tune_003d_0040var_007bTUNE_007d_0022_0029_007d-function-attribute_002c-PowerPC-3291"></a>Specify the architecture to tune for when compiling the function. If
|
||
|
|
you do not specify the <code>target("tune=</code><var>TUNE</var><code>")</code> attribute and
|
||
|
|
you do specify the <code>target("cpu=</code><var>CPU</var><code>")</code> attribute,
|
||
|
|
compilation tunes for the <var>CPU</var> architecture, and not the
|
||
|
|
default tuning specified on the command line.
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<p>When compiling for Nios II, the following options are allowed:
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt>‘<samp><span class="samp">custom-</span><var>insn</var><span class="samp">=</span><var>N</var></samp>’<dt>‘<samp><span class="samp">no-custom-</span><var>insn</var></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022custom_002d_0040var_007binsn_007d_003d_0040var_007bN_007d_0022_0029_007d-function-attribute_002c-Nios-II-3292"></a><a name="index-g_t_0040code_007btarget_0028_0022no_002dcustom_002d_0040var_007binsn_007d_0022_0029_007d-function-attribute_002c-Nios-II-3293"></a>Each ‘<samp><span class="samp">custom-</span><var>insn</var><span class="samp">=</span><var>N</var></samp>’ attribute locally enables use of a
|
||
|
|
custom instruction with encoding <var>N</var> when generating code that uses
|
||
|
|
<var>insn</var>. Similarly, ‘<samp><span class="samp">no-custom-</span><var>insn</var></samp>’ locally inhibits use of
|
||
|
|
the custom instruction <var>insn</var>.
|
||
|
|
These target attributes correspond to the
|
||
|
|
<samp><span class="option">-mcustom-</span><var>insn</var><span class="option">=</span><var>N</var></samp> and <samp><span class="option">-mno-custom-</span><var>insn</var></samp>
|
||
|
|
command-line options, and support the same set of <var>insn</var> keywords.
|
||
|
|
See <a href="Nios-II-Options.html#Nios-II-Options">Nios II Options</a>, for more information.
|
||
|
|
|
||
|
|
<br><dt>‘<samp><span class="samp">custom-fpu-cfg=</span><var>name</var></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022custom_002dfpu_002dcfg_003d_0040var_007bname_007d_0022_0029_007d-function-attribute_002c-Nios-II-3294"></a>This attribute corresponds to the <samp><span class="option">-mcustom-fpu-cfg=</span><var>name</var></samp>
|
||
|
|
command-line option, to select a predefined set of custom instructions
|
||
|
|
named <var>name</var>.
|
||
|
|
See <a href="Nios-II-Options.html#Nios-II-Options">Nios II Options</a>, for more information.
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<p>On the x86 and PowerPC back ends, the inliner does not inline a
|
||
|
|
function that has different target options than the caller, unless the
|
||
|
|
callee has a subset of the target options of the caller. For example
|
||
|
|
a function declared with <code>target("sse3")</code> can inline a function
|
||
|
|
with <code>target("sse2")</code>, since <code>-msse3</code> implies <code>-msse2</code>.
|
||
|
|
|
||
|
|
<br><dt><code>trap_exit</code><dd><a name="index-g_t_0040code_007btrap_005fexit_007d-function-attribute_002c-SH-3295"></a>Use this attribute on the SH for an <code>interrupt_handler</code> to return using
|
||
|
|
<code>trapa</code> instead of <code>rte</code>. This attribute expects an integer
|
||
|
|
argument specifying the trap number to be used.
|
||
|
|
|
||
|
|
<br><dt><code>trapa_handler</code><dd><a name="index-g_t_0040code_007btrapa_005fhandler_007d-function-attribute_002c-SH-3296"></a>On SH targets this function attribute is similar to <code>interrupt_handler</code>
|
||
|
|
but it does not save and restore all registers.
|
||
|
|
|
||
|
|
<br><dt><code>unused</code><dd><a name="index-g_t_0040code_007bunused_007d-function-attribute-3297"></a>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.
|
||
|
|
|
||
|
|
<br><dt><code>used</code><dd><a name="index-g_t_0040code_007bused_007d-function-attribute-3298"></a>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>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.
|
||
|
|
|
||
|
|
<br><dt><code>vector</code><dd><a name="index-g_t_0040code_007bvector_007d-function-attribute_002c-RX-3299"></a>This RX attribute is similar to the <code>interrupt</code> attribute, including its
|
||
|
|
parameters, but does not make the function an interrupt-handler type
|
||
|
|
function (i.e. it retains the normal C function calling ABI). See the
|
||
|
|
<code>interrupt</code> attribute for a description of its arguments.
|
||
|
|
|
||
|
|
<br><dt><code>version_id</code><dd><a name="index-g_t_0040code_007bversion_005fid_007d-function-attribute_002c-IA_002d64-3300"></a>This IA-64 HP-UX attribute, attached to a global variable or function, renames a
|
||
|
|
symbol to contain a version string, thus allowing for function level
|
||
|
|
versioning. HP-UX system header files may use function level versioning
|
||
|
|
for some system calls.
|
||
|
|
|
||
|
|
<pre class="smallexample"> extern int foo () __attribute__((version_id ("20040821")));
|
||
|
|
</pre>
|
||
|
|
<p class="noindent">Calls to <var>foo</var> are mapped to calls to <var>foo{20040821}</var>.
|
||
|
|
|
||
|
|
<br><dt><code>visibility ("</code><var>visibility_type</var><code>")</code><dd><a name="index-g_t_0040code_007bvisibility_007d-function-attribute-3301"></a>This attribute affects the linkage of the declaration to which it is attached.
|
||
|
|
There are four supported <var>visibility_type</var> values: default,
|
||
|
|
hidden, protected or internal visibility.
|
||
|
|
|
||
|
|
<pre class="smallexample"> void __attribute__ ((visibility ("protected")))
|
||
|
|
f () { /* <span class="roman">Do something.</span> */; }
|
||
|
|
int i __attribute__ ((visibility ("hidden")));
|
||
|
|
</pre>
|
||
|
|
<p>The possible values of <var>visibility_type</var> correspond to the
|
||
|
|
visibility settings in the ELF gABI.
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<!-- keep this list of visibilities in alphabetical order. -->
|
||
|
|
|
||
|
|
<dt><dfn>default</dfn><dd>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>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>On Darwin, default visibility means that the declaration is visible to
|
||
|
|
other modules.
|
||
|
|
|
||
|
|
<p>Default visibility corresponds to “external linkage” in the language.
|
||
|
|
|
||
|
|
<br><dt><dfn>hidden</dfn><dd>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.
|
||
|
|
|
||
|
|
<br><dt><dfn>internal</dfn><dd>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.
|
||
|
|
|
||
|
|
<br><dt><dfn>protected</dfn><dd>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.
|
||
|
|
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<p>All visibilities are supported on many, but not all, ELF targets
|
||
|
|
(supported when the assembler supports the ‘<samp><span class="samp">.visibility</span></samp>’
|
||
|
|
pseudo-op). Default visibility is supported everywhere. Hidden
|
||
|
|
visibility is supported on Darwin targets.
|
||
|
|
|
||
|
|
<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>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>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>A C++ namespace declaration can also have the visibility attribute.
|
||
|
|
|
||
|
|
<pre class="smallexample"> namespace nspace1 __attribute__ ((visibility ("protected")))
|
||
|
|
{ /* <span class="roman">Do something.</span> */; }
|
||
|
|
</pre>
|
||
|
|
<p>This attribute applies only to the particular namespace body, not to
|
||
|
|
other definitions of the same namespace; it is equivalent to using
|
||
|
|
‘<samp><span class="samp">#pragma GCC visibility</span></samp>’ before and after the namespace
|
||
|
|
definition (see <a href="Visibility-Pragmas.html#Visibility-Pragmas">Visibility Pragmas</a>).
|
||
|
|
|
||
|
|
<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>If both the template and enclosing class have explicit visibility, the
|
||
|
|
visibility from the template is used.
|
||
|
|
|
||
|
|
<br><dt><code>vliw</code><dd><a name="index-g_t_0040code_007bvliw_007d-function-attribute_002c-MeP-3302"></a>On MeP, the <code>vliw</code> attribute tells the compiler to emit
|
||
|
|
instructions in VLIW mode instead of core mode. Note that this
|
||
|
|
attribute is not allowed unless a VLIW coprocessor has been configured
|
||
|
|
and enabled through command-line options.
|
||
|
|
|
||
|
|
<br><dt><code>warn_unused_result</code><dd><a name="index-g_t_0040code_007bwarn_005funused_005fresult_007d-function-attribute-3303"></a>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>.
|
||
|
|
|
||
|
|
<pre class="smallexample"> int fn () __attribute__ ((warn_unused_result));
|
||
|
|
int foo ()
|
||
|
|
{
|
||
|
|
if (fn () < 0) return -1;
|
||
|
|
fn ();
|
||
|
|
return 0;
|
||
|
|
}
|
||
|
|
</pre>
|
||
|
|
<p class="noindent">results in warning on line 5.
|
||
|
|
|
||
|
|
<br><dt><code>weak</code><dd><a name="index-g_t_0040code_007bweak_007d-function-attribute-3304"></a>The <code>weak</code> attribute causes the declaration 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. Weak symbols are supported
|
||
|
|
for ELF targets, and also for a.out targets when using the GNU assembler
|
||
|
|
and linker.
|
||
|
|
|
||
|
|
<br><dt><code>weakref</code><dt><code>weakref ("</code><var>target</var><code>")</code><dd><a name="index-g_t_0040code_007bweakref_007d-function-attribute-3305"></a>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. Optionally, the <var>target</var> may be given as
|
||
|
|
an argument to <code>weakref</code> itself. In either case, <code>weakref</code>
|
||
|
|
implicitly marks the declaration 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>.
|
||
|
|
|
||
|
|
<pre class="smallexample"> static int x() __attribute__ ((weakref ("y")));
|
||
|
|
/* is equivalent to... */
|
||
|
|
static int x() __attribute__ ((weak, weakref, alias ("y")));
|
||
|
|
/* and to... */
|
||
|
|
static int x() __attribute__ ((weakref));
|
||
|
|
static int x() __attribute__ ((alias ("y")));
|
||
|
|
</pre>
|
||
|
|
<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>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 reloadable link on them.
|
||
|
|
|
||
|
|
<p>At present, a declaration to which <code>weakref</code> is attached can
|
||
|
|
only be <code>static</code>.
|
||
|
|
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<p>You can specify multiple attributes in a declaration by separating them
|
||
|
|
by commas within the double parentheses or by immediately following an
|
||
|
|
attribute declaration with another attribute declaration.
|
||
|
|
|
||
|
|
<p><a name="index-g_t_0040code_007b_0023pragma_007d_002c-reason-for-not-using-3306"></a><a name="index-pragma_002c-reason-for-not-using-3307"></a>Some people object to the <code>__attribute__</code> feature, suggesting that
|
||
|
|
ISO C's <code>#pragma</code> should be used instead. At the time
|
||
|
|
<code>__attribute__</code> was designed, there were two reasons for not doing
|
||
|
|
this.
|
||
|
|
|
||
|
|
<ol type=1 start=1>
|
||
|
|
<li>It is impossible to generate <code>#pragma</code> commands from a macro.
|
||
|
|
|
||
|
|
<li>There is no telling what the same <code>#pragma</code> might mean in another
|
||
|
|
compiler.
|
||
|
|
</ol>
|
||
|
|
|
||
|
|
<p>These two reasons applied to almost any application that might have been
|
||
|
|
proposed for <code>#pragma</code>. It was basically a mistake to use
|
||
|
|
<code>#pragma</code> for <em>anything</em>.
|
||
|
|
|
||
|
|
<p>The ISO C99 standard includes <code>_Pragma</code>, which now allows pragmas
|
||
|
|
to be generated from macros. In addition, a <code>#pragma GCC</code>
|
||
|
|
namespace is now in use for GCC-specific pragmas. However, it has been
|
||
|
|
found convenient to use <code>__attribute__</code> to achieve a natural
|
||
|
|
attachment of attributes to their corresponding declarations, whereas
|
||
|
|
<code>#pragma GCC</code> is of use for constructs that do not naturally form
|
||
|
|
part of the grammar. See <a href="Pragmas.html#Pragmas">Pragmas Accepted by GCC</a>.
|
||
|
|
|
||
|
|
</body></html>
|
||
|
|
|