| <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> |
| <html> |
| <!-- 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. --> |
| <!-- Created by GNU Texinfo 5.2, http://www.gnu.org/software/texinfo/ --> |
| <head> |
| <title>Using the GNU Compiler Collection (GCC): Function Attributes</title> |
| |
| <meta name="description" content="Using the GNU Compiler Collection (GCC): Function Attributes"> |
| <meta name="keywords" content="Using the GNU Compiler Collection (GCC): Function Attributes"> |
| <meta name="resource-type" content="document"> |
| <meta name="distribution" content="global"> |
| <meta name="Generator" content="makeinfo"> |
| <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> |
| <link href="index.html#Top" rel="start" title="Top"> |
| <link href="Option-Index.html#Option-Index" rel="index" title="Option Index"> |
| <link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> |
| <link href="C-Extensions.html#C-Extensions" rel="up" title="C Extensions"> |
| <link href="Label-Attributes.html#Label-Attributes" rel="next" title="Label Attributes"> |
| <link href="Mixed-Declarations.html#Mixed-Declarations" rel="prev" title="Mixed Declarations"> |
| <style type="text/css"> |
| <!-- |
| a.summary-letter {text-decoration: none} |
| blockquote.smallquotation {font-size: smaller} |
| div.display {margin-left: 3.2em} |
| div.example {margin-left: 3.2em} |
| div.indentedblock {margin-left: 3.2em} |
| div.lisp {margin-left: 3.2em} |
| div.smalldisplay {margin-left: 3.2em} |
| div.smallexample {margin-left: 3.2em} |
| div.smallindentedblock {margin-left: 3.2em; font-size: smaller} |
| div.smalllisp {margin-left: 3.2em} |
| kbd {font-style:oblique} |
| pre.display {font-family: inherit} |
| pre.format {font-family: inherit} |
| pre.menu-comment {font-family: serif} |
| pre.menu-preformatted {font-family: serif} |
| pre.smalldisplay {font-family: inherit; font-size: smaller} |
| pre.smallexample {font-size: smaller} |
| pre.smallformat {font-family: inherit; font-size: smaller} |
| pre.smalllisp {font-size: smaller} |
| span.nocodebreak {white-space:nowrap} |
| span.nolinebreak {white-space:nowrap} |
| span.roman {font-family:serif; font-weight:normal} |
| span.sansserif {font-family:sans-serif; font-weight:normal} |
| ul.no-bullet {list-style: none} |
| --> |
| </style> |
| |
| |
| </head> |
| |
| <body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> |
| <a name="Function-Attributes"></a> |
| <div class="header"> |
| <p> |
| Next: <a href="Label-Attributes.html#Label-Attributes" accesskey="n" rel="next">Label Attributes</a>, Previous: <a href="Mixed-Declarations.html#Mixed-Declarations" accesskey="p" rel="prev">Mixed Declarations</a>, Up: <a href="C-Extensions.html#C-Extensions" accesskey="u" rel="up">C Extensions</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Option-Index.html#Option-Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <hr> |
| <a name="Declaring-Attributes-of-Functions"></a> |
| <h3 class="section">6.31 Declaring Attributes of Functions</h3> |
| <a name="index-function-attributes"></a> |
| <a name="index-declaring-attributes-of-functions"></a> |
| <a name="index-functions-that-never-return"></a> |
| <a name="index-functions-that-return-more-than-once"></a> |
| <a name="index-functions-that-have-no-side-effects"></a> |
| <a name="index-functions-in-arbitrary-sections"></a> |
| <a name="index-functions-that-behave-like-malloc"></a> |
| <a name="index-volatile-applied-to-function"></a> |
| <a name="index-const-applied-to-function"></a> |
| <a name="index-functions-with-printf_002c-scanf_002c-strftime-or-strfmon-style-arguments"></a> |
| <a name="index-functions-with-non_002dnull-pointer-arguments"></a> |
| <a name="index-functions-that-are-passed-arguments-in-registers-on-x86_002d32"></a> |
| <a name="index-functions-that-pop-the-argument-stack-on-x86_002d32"></a> |
| <a name="index-functions-that-do-not-pop-the-argument-stack-on-x86_002d32"></a> |
| <a name="index-functions-that-have-different-compilation-options-on-x86_002d32"></a> |
| <a name="index-functions-that-have-different-optimization-options"></a> |
| <a name="index-functions-that-are-dynamically-resolved"></a> |
| |
| <p>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> |
| <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> |
| <p>GCC plugins may provide their own attributes. |
| </p> |
| <p>You may also specify attributes with ‘<samp>__</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> |
| <p>See <a href="Attribute-Syntax.html#Attribute-Syntax">Attribute Syntax</a>, for details of the exact syntax for using |
| attributes. |
| </p> |
| <dl compact="compact"> |
| <dt><code>alias ("<var>target</var>")</code></dt> |
| <dd><a name="index-alias-function-attribute"></a> |
| <p>The <code>alias</code> attribute causes the declaration to be emitted as an |
| alias for another symbol, which must be specified. For instance, |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample">void __f () { /* <span class="roman">Do something.</span> */; } |
| void f () __attribute__ ((weak, alias ("__f"))); |
| </pre></div> |
| |
| <p>defines ‘<samp>f</samp>’ to be a weak alias for ‘<samp>__f</samp>’. In C++, the |
| mangled name for the target must be used. It is an error if ‘<samp>__f</samp>’ |
| is not defined in the same translation unit. |
| </p> |
| <p>Not all target machines support this attribute. |
| </p> |
| </dd> |
| <dt><code>aligned (<var>alignment</var>)</code></dt> |
| <dd><a name="index-aligned-function-attribute"></a> |
| <p>This attribute specifies a minimum alignment for the function, |
| measured in bytes. |
| </p> |
| <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>-falign-functions</samp> (see <a href="Optimize-Options.html#Optimize-Options">Optimize Options</a>) option for this |
| function. |
| </p> |
| <p>Note that the effectiveness of <code>aligned</code> attributes may be |
| limited by inherent limitations in 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> |
| <p>The <code>aligned</code> attribute can also be used for variables and fields |
| (see <a href="Variable-Attributes.html#Variable-Attributes">Variable Attributes</a>.) |
| </p> |
| </dd> |
| <dt><code>alloc_size</code></dt> |
| <dd><a name="index-alloc_005fsize-function-attribute"></a> |
| <p>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> |
| <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> |
| <p>For instance, |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample">void* my_calloc(size_t, size_t) __attribute__((alloc_size(1,2))) |
| void* my_realloc(void*, size_t) __attribute__((alloc_size(2))) |
| </pre></div> |
| |
| <p>declares that <code>my_calloc</code> returns memory of the size given by |
| the product of parameter 1 and 2 and that <code>my_realloc</code> returns memory |
| of the size given by parameter 2. |
| </p> |
| </dd> |
| <dt><code>alloc_align</code></dt> |
| <dd><a name="index-alloc_005falign-function-attribute"></a> |
| <p>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> |
| <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> |
| <p>For instance, |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample">void* my_memalign(size_t, size_t) __attribute__((alloc_align(1))) |
| </pre></div> |
| |
| <p>declares that <code>my_memalign</code> returns memory with minimum alignment |
| given by parameter 1. |
| </p> |
| </dd> |
| <dt><code>assume_aligned</code></dt> |
| <dd><a name="index-assume_005faligned-function-attribute"></a> |
| <p>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> |
| <p>For instance |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample">void* my_alloc1(size_t) __attribute__((assume_aligned(16))) |
| void* my_alloc2(size_t) __attribute__((assume_aligned(32, 8))) |
| </pre></div> |
| |
| <p>declares that <code>my_alloc1</code> returns 16-byte aligned pointer and |
| that <code>my_alloc2</code> returns a pointer whose value modulo 32 is equal |
| to 8. |
| </p> |
| </dd> |
| <dt><code>always_inline</code></dt> |
| <dd><a name="index-always_005finline-function-attribute"></a> |
| <p>Generally, functions are not inlined unless optimization is specified. |
| For functions declared inline, this attribute inlines the function |
| independent of any restrictions that otherwise apply to inlining. |
| Failure to inline such a function is diagnosed as an error. |
| Note that if such a function is called indirectly the compiler may |
| or may not inline it depending on optimization level and a failure |
| to inline an indirect call may or may not be diagnosed. |
| </p> |
| </dd> |
| <dt><code>gnu_inline</code></dt> |
| <dd><a name="index-gnu_005finline-function-attribute"></a> |
| <p>This attribute should be used with a function that is also declared |
| with the <code>inline</code> keyword. It directs GCC to treat the function |
| as if it were defined in gnu90 mode even when compiling in C99 or |
| gnu99 mode. |
| </p> |
| <p>If the function is declared <code>extern</code>, then this definition of the |
| function is used only for inlining. In no case is the function |
| compiled as a standalone function, not even if you take its address |
| explicitly. Such an address becomes an external reference, as if you |
| had only declared the function, and had not defined it. This has |
| almost the effect of a macro. The way to use this is to put a |
| function definition in a header file with this attribute, and put |
| another copy of the function, without <code>extern</code>, in a library |
| file. The definition in the header file causes most calls to the |
| function to be inlined. If any uses of the function remain, they |
| refer to the single copy in the library. Note that the two |
| definitions of the functions need not be precisely the same, although |
| if they do not have the same effect your program may behave oddly. |
| </p> |
| <p>In C, if the function is neither <code>extern</code> nor <code>static</code>, then |
| the function is compiled as a standalone function, as well as being |
| inlined where possible. |
| </p> |
| <p>This is how GCC traditionally handled functions declared |
| <code>inline</code>. Since ISO C99 specifies a different semantics for |
| <code>inline</code>, this function attribute is provided as a transition |
| measure and as a useful feature in its own right. This attribute is |
| available in GCC 4.1.3 and later. It is available if either of the |
| preprocessor macros <code>__GNUC_GNU_INLINE__</code> or |
| <code>__GNUC_STDC_INLINE__</code> are defined. See <a href="Inline.html#Inline">An Inline |
| Function is As Fast As a Macro</a>. |
| </p> |
| <p>In C++, this attribute does not depend on <code>extern</code> in any way, |
| but it still requires the <code>inline</code> keyword to enable its special |
| behavior. |
| </p> |
| </dd> |
| <dt><code>artificial</code></dt> |
| <dd><a name="index-artificial-function-attribute"></a> |
| <p>This attribute is useful for small inline wrappers that if possible |
| should appear during debugging as a unit. Depending on the debug |
| info format it either means marking the function as artificial |
| or using the caller location for all instructions within the inlined |
| body. |
| </p> |
| </dd> |
| <dt><code>bank_switch</code></dt> |
| <dd><a name="index-bank_005fswitch-function-attribute_002c-M32C"></a> |
| <p>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. |
| </p> |
| </dd> |
| <dt><code>flatten</code></dt> |
| <dd><a name="index-flatten-function-attribute"></a> |
| <p>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. |
| </p> |
| </dd> |
| <dt><code>error ("<var>message</var>")</code></dt> |
| <dd><a name="index-error-function-attribute"></a> |
| <p>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. |
| </p> |
| </dd> |
| <dt><code>warning ("<var>message</var>")</code></dt> |
| <dd><a name="index-warning-function-attribute"></a> |
| <p>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. |
| </p> |
| </dd> |
| <dt><code>cdecl</code></dt> |
| <dd><a name="index-cdecl-function-attribute_002c-x86_002d32"></a> |
| <a name="index-functions-that-do-pop-the-argument-stack-on-x86_002d32"></a> |
| <a name="index-mrtd-2"></a> |
| <p>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>-mrtd</samp> switch. |
| </p> |
| </dd> |
| <dt><code>const</code></dt> |
| <dd><a name="index-const-function-attribute"></a> |
| <p>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"></a> |
| <p>Note that a function that has pointer arguments and examines the data |
| pointed to must <em>not</em> be declared <code>const</code>. 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>. |
| </p> |
| </dd> |
| <dt><code>constructor</code></dt> |
| <dt><code>destructor</code></dt> |
| <dt><code>constructor (<var>priority</var>)</code></dt> |
| <dt><code>destructor (<var>priority</var>)</code></dt> |
| <dd><a name="index-constructor-function-attribute"></a> |
| <a name="index-destructor-function-attribute"></a> |
| <p>The <code>constructor</code> attribute causes the function to be called |
| automatically before execution enters <code>main ()</code>. Similarly, the |
| <code>destructor</code> attribute causes the function to be called |
| automatically after <code>main ()</code> completes or <code>exit ()</code> is |
| called. Functions with these attributes are useful for |
| initializing data that is used implicitly during the execution of |
| the program. |
| </p> |
| <p>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> |
| <p>These attributes are not currently implemented for Objective-C. |
| </p> |
| </dd> |
| <dt><code>deprecated</code></dt> |
| <dt><code>deprecated (<var>msg</var>)</code></dt> |
| <dd><a name="index-deprecated-function-attribute"></a> |
| <p>The <code>deprecated</code> attribute results in a warning if the function |
| is used anywhere in the source file. This is useful when identifying |
| functions that are expected to be removed in a future version of a |
| program. The warning also includes the location of the declaration |
| of the deprecated function, to enable users to easily find further |
| information about why the function is deprecated, or what they should |
| do instead. Note that the warnings only occurs for uses: |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample">int old_fn () __attribute__ ((deprecated)); |
| int old_fn (); |
| int (*fn_ptr)() = old_fn; |
| </pre></div> |
| |
| <p>results in a warning on line 3 but not line 2. The optional <var>msg</var> |
| argument, which must be a string, is printed in the warning if |
| present. |
| </p> |
| <p>The <code>deprecated</code> attribute can also be used for variables and |
| types (see <a href="Variable-Attributes.html#Variable-Attributes">Variable Attributes</a>, see <a href="Type-Attributes.html#Type-Attributes">Type Attributes</a>.) |
| </p> |
| </dd> |
| <dt><code>disinterrupt</code></dt> |
| <dd><a name="index-disinterrupt-function-attribute_002c-Epiphany"></a> |
| <a name="index-disinterrupt-function-attribute_002c-MeP"></a> |
| <p>On Epiphany and MeP targets, this attribute causes the compiler to emit |
| instructions to disable interrupts for the duration of the given |
| function. |
| </p> |
| </dd> |
| <dt><code>dllexport</code></dt> |
| <dd><a name="index-dllexport-function-attribute"></a> |
| <a name="index-_005f_005fdeclspec_0028dllexport_0029"></a> |
| <p>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> |
| <p>You can use <code>__declspec(dllexport)</code> as a synonym for |
| <code>__attribute__ ((dllexport))</code> for compatibility with other |
| compilers. |
| </p> |
| <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> |
| <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>-fno-keep-inline-dllexport</samp>, which tells GCC to |
| ignore the attribute for inlined functions unless the |
| <samp>-fkeep-inline-functions</samp> flag is used instead. |
| </p> |
| <p>The attribute is ignored for undefined symbols. |
| </p> |
| <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> |
| <p>For Microsoft Windows targets there are alternative methods for |
| including the symbol in the DLL’s export table such as using a |
| <samp>.def</samp> file with an <code>EXPORTS</code> section or, with GNU ld, using |
| the <samp>--export-all</samp> linker flag. |
| </p> |
| </dd> |
| <dt><code>dllimport</code></dt> |
| <dd><a name="index-dllimport-function-attribute"></a> |
| <a name="index-_005f_005fdeclspec_0028dllimport_0029"></a> |
| <p>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> |
| <p>You can use <code>__declspec(dllimport)</code> as a synonym for |
| <code>__attribute__ ((dllimport))</code> for compatibility with other |
| compilers. |
| </p> |
| <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> |
| <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> |
| <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> |
| <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> |
| <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>--enable-auto-import</samp> switch to the GNU linker. As with |
| functions, using the attribute for a variable eliminates a thunk in |
| the DLL. |
| </p> |
| <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>-mnop-fun-dllimport</samp> flag. |
| </p> |
| </dd> |
| <dt><code>exception</code></dt> |
| <dd><a name="index-exception-function-attribute"></a> |
| <a name="index-exception-handler-functions_002c-NDS32"></a> |
| <p>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. |
| </p> |
| </dd> |
| <dt><code>exception_handler</code></dt> |
| <dd><a name="index-exception_005fhandler-function-attribute"></a> |
| <a name="index-exception-handler-functions_002c-Blackfin"></a> |
| <p>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. |
| </p> |
| </dd> |
| <dt><code>externally_visible</code></dt> |
| <dd><a name="index-externally_005fvisible-function-attribute"></a> |
| <p>This attribute, attached to a global variable or function, nullifies |
| the effect of the <samp>-fwhole-program</samp> command-line option, so the |
| object remains visible outside the current compilation unit. |
| </p> |
| <p>If <samp>-fwhole-program</samp> is used together with <samp>-flto</samp> and |
| <code>gold</code> is used as the linker plugin, |
| <code>externally_visible</code> attributes are automatically added to functions |
| (not variable yet due to a current <code>gold</code> issue) |
| that are accessed outside of LTO objects according to resolution file |
| produced by <code>gold</code>. |
| For other linkers that cannot generate resolution file, |
| explicit <code>externally_visible</code> attributes are still necessary. |
| </p> |
| </dd> |
| <dt><code>far</code></dt> |
| <dd><a name="index-far-function-attribute"></a> |
| |
| <p>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. |
| </p> |
| </dd> |
| <dt><code>fast_interrupt</code></dt> |
| <dd><a name="index-fast_005finterrupt-function-attribute_002c-M32C"></a> |
| <a name="index-fast_005finterrupt-function-attribute_002c-RX"></a> |
| <p>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>. |
| </p> |
| </dd> |
| <dt><code>fastcall</code></dt> |
| <dd><a name="index-fastcall-function-attribute_002c-x86_002d32"></a> |
| <a name="index-functions-that-pop-the-argument-stack-on-x86_002d32-1"></a> |
| <p>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. |
| </p> |
| </dd> |
| <dt><code>thiscall</code></dt> |
| <dd><a name="index-thiscall-function-attribute_002c-x86_002d32"></a> |
| <a name="index-functions-that-pop-the-argument-stack-on-x86_002d32-2"></a> |
| <p>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. |
| </p> |
| </dd> |
| <dt><code>format (<var>archetype</var>, <var>string-index</var>, <var>first-to-check</var>)</code></dt> |
| <dd><a name="index-format-function-attribute"></a> |
| <a name="index-Wformat-3"></a> |
| <p>The <code>format</code> attribute specifies that a function takes <code>printf</code>, |
| <code>scanf</code>, <code>strftime</code> or <code>strfmon</code> style arguments that |
| should be type-checked against a format string. For example, the |
| declaration: |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample">extern int |
| my_printf (void *my_object, const char *my_format, ...) |
| __attribute__ ((format (printf, 2, 3))); |
| </pre></div> |
| |
| <p>causes the compiler to check the arguments in calls to <code>my_printf</code> |
| for consistency with the <code>printf</code> style format string argument |
| <code>my_format</code>. |
| </p> |
| <p>The parameter <var>archetype</var> determines how the format string is |
| interpreted, and should be <code>printf</code>, <code>scanf</code>, <code>strftime</code>, |
| <code>gnu_printf</code>, <code>gnu_scanf</code>, <code>gnu_strftime</code> or |
| <code>strfmon</code>. (You can also use <code>__printf__</code>, |
| <code>__scanf__</code>, <code>__strftime__</code> or <code>__strfmon__</code>.) On |
| MinGW targets, <code>ms_printf</code>, <code>ms_scanf</code>, and |
| <code>ms_strftime</code> are also present. |
| <var>archetype</var> values such as <code>printf</code> refer to the formats accepted |
| by the system’s C runtime library, |
| while values prefixed with ‘<samp>gnu_</samp>’ always refer |
| to the formats accepted by the GNU C Library. On Microsoft Windows |
| targets, values prefixed with ‘<samp>ms_</samp>’ refer to the formats accepted by the |
| <samp>msvcrt.dll</samp> library. |
| The parameter <var>string-index</var> |
| specifies which argument is the format string argument (starting |
| from 1), while <var>first-to-check</var> is the number of the first |
| argument to check against the format string. For functions |
| where the arguments are not available to be checked (such as |
| <code>vprintf</code>), specify the third parameter as zero. In this case the |
| compiler only checks the format string for consistency. For |
| <code>strftime</code> formats, the third parameter is required to be zero. |
| Since non-static C++ methods have an implicit <code>this</code> argument, the |
| arguments of such methods should be counted from two, not one, when |
| giving values for <var>string-index</var> and <var>first-to-check</var>. |
| </p> |
| <p>In the example above, the format string (<code>my_format</code>) is the second |
| argument of the function <code>my_print</code>, and the arguments to check |
| start with the third argument, so the correct parameters for the format |
| attribute are 2 and 3. |
| </p> |
| <a name="index-ffreestanding-3"></a> |
| <a name="index-fno_002dbuiltin-2"></a> |
| <p>The <code>format</code> attribute allows you to identify your own functions |
| that take format strings as arguments, so that GCC can check the |
| calls to these functions for errors. The compiler always (unless |
| <samp>-ffreestanding</samp> or <samp>-fno-builtin</samp> is used) checks formats |
| for the standard library functions <code>printf</code>, <code>fprintf</code>, |
| <code>sprintf</code>, <code>scanf</code>, <code>fscanf</code>, <code>sscanf</code>, <code>strftime</code>, |
| <code>vprintf</code>, <code>vfprintf</code> and <code>vsprintf</code> whenever such |
| warnings are requested (using <samp>-Wformat</samp>), so there is no need to |
| modify the header file <samp>stdio.h</samp>. In C99 mode, the functions |
| <code>snprintf</code>, <code>vsnprintf</code>, <code>vscanf</code>, <code>vfscanf</code> and |
| <code>vsscanf</code> are also checked. Except in strictly conforming C |
| standard modes, the X/Open function <code>strfmon</code> is also checked as |
| are <code>printf_unlocked</code> and <code>fprintf_unlocked</code>. |
| See <a href="C-Dialect-Options.html#C-Dialect-Options">Options Controlling C Dialect</a>. |
| </p> |
| <p>For Objective-C dialects, <code>NSString</code> (or <code>__NSString__</code>) is |
| recognized in the same context. Declarations including these format attributes |
| are parsed for correct syntax, however the result of checking of such format |
| strings is not yet defined, and is not carried out by this version of the |
| compiler. |
| </p> |
| <p>The target may also provide additional types of format checks. |
| See <a href="Target-Format-Checks.html#Target-Format-Checks">Format Checks Specific to Particular |
| Target Machines</a>. |
| </p> |
| </dd> |
| <dt><code>format_arg (<var>string-index</var>)</code></dt> |
| <dd><a name="index-format_005farg-function-attribute"></a> |
| <a name="index-Wformat_002dnonliteral-1"></a> |
| <p>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: |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample">extern char * |
| my_dgettext (char *my_domain, const char *my_format) |
| __attribute__ ((format_arg (2))); |
| </pre></div> |
| |
| <p>causes the compiler to check the arguments in calls to a <code>printf</code>, |
| <code>scanf</code>, <code>strftime</code> or <code>strfmon</code> type function, whose |
| format string argument is a call to the <code>my_dgettext</code> function, for |
| consistency with the format string argument <code>my_format</code>. If the |
| <code>format_arg</code> attribute had not been specified, all the compiler |
| could tell in such calls to format functions would be that the format |
| string argument is not constant; this would generate a warning when |
| <samp>-Wformat-nonliteral</samp> is used, but the calls could not be checked |
| without the attribute. |
| </p> |
| <p>The parameter <var>string-index</var> specifies which argument is the format |
| string argument (starting from one). Since non-static C++ methods have |
| an implicit <code>this</code> argument, the arguments of such methods should |
| be counted from two. |
| </p> |
| <p>The <code>format_arg</code> attribute allows you to identify your own |
| functions that modify format strings, so that GCC can check the |
| calls to <code>printf</code>, <code>scanf</code>, <code>strftime</code> or <code>strfmon</code> |
| type function whose operands are a call to one of your own function. |
| The compiler always treats <code>gettext</code>, <code>dgettext</code>, and |
| <code>dcgettext</code> in this manner except when strict ISO C support is |
| requested by <samp>-ansi</samp> or an appropriate <samp>-std</samp> option, or |
| <samp>-ffreestanding</samp> or <samp>-fno-builtin</samp> |
| is used. See <a href="C-Dialect-Options.html#C-Dialect-Options">Options |
| Controlling C Dialect</a>. |
| </p> |
| <p>For Objective-C dialects, the <code>format-arg</code> attribute may refer to an |
| <code>NSString</code> reference for compatibility with the <code>format</code> attribute |
| above. |
| </p> |
| <p>The target may also allow additional types in <code>format-arg</code> attributes. |
| See <a href="Target-Format-Checks.html#Target-Format-Checks">Format Checks Specific to Particular |
| Target Machines</a>. |
| </p> |
| </dd> |
| <dt><code>function_vector</code></dt> |
| <dd><a name="index-function_005fvector-function-attribute_002c-H8_002f300"></a> |
| <a name="index-function_005fvector-function-attribute_002c-M16C_002fM32C"></a> |
| <a name="index-function_005fvector-function-attribute_002c-SH"></a> |
| <a name="index-calling-functions-through-the-function-vector-on-H8_002f300_002c-M16C_002c-M32C-and-SH2A-processors"></a> |
| <p>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> |
| <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> |
| <p>Please refer the example of M16C target, to see the use of this |
| attribute while declaring a function, |
| </p> |
| <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> |
| <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> |
| <p>In the following example 2 bytes are saved for each call to |
| function <code>foo</code>. |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample">void foo (void) __attribute__((function_vector(0x18))); |
| void foo (void) |
| { |
| } |
| |
| void bar (void) |
| { |
| foo(); |
| } |
| </pre></div> |
| |
| <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> |
| <p>This attribute is ignored for R8C target. |
| </p> |
| </dd> |
| <dt><code>ifunc ("<var>resolver</var>")</code></dt> |
| <dd><a name="index-ifunc-function-attribute"></a> |
| <p>The <code>ifunc</code> attribute is used to mark a function as an indirect |
| function using the STT_GNU_IFUNC symbol type extension to the ELF |
| standard. This allows the resolution of the symbol value to be |
| determined dynamically at load time, and an optimized version of the |
| routine 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: |
| </p> |
| <div class="smallexample"> |
| <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></div> |
| |
| <p>The exported header file declaring the function the user calls would |
| contain: |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample">extern void *memcpy (void *, const void *, size_t); |
| </pre></div> |
| |
| <p>allowing the user to call 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: |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample">void *memcpy (void *, const void *, size_t) |
| __attribute__ ((ifunc ("resolve_memcpy"))); |
| </pre></div> |
| |
| <p>Indirect functions cannot be weak. Binutils version 2.20.1 or higher |
| and GNU C Library version 2.11.1 are required to use this feature. |
| </p> |
| </dd> |
| <dt><code>interrupt</code></dt> |
| <dd><a name="index-interrupt-function-attribute_002c-ARC"></a> |
| <a name="index-interrupt-function-attribute_002c-ARM"></a> |
| <a name="index-interrupt-function-attribute_002c-AVR"></a> |
| <a name="index-interrupt-function-attribute_002c-CR16"></a> |
| <a name="index-interrupt-function-attribute_002c-Epiphany"></a> |
| <a name="index-interrupt-function-attribute_002c-M32C"></a> |
| <a name="index-interrupt-function-attribute_002c-M32R_002fD"></a> |
| <a name="index-interrupt-function-attribute_002c-m68k"></a> |
| <a name="index-interrupt-function-attribute_002c-MeP"></a> |
| <a name="index-interrupt-function-attribute_002c-MIPS"></a> |
| <a name="index-interrupt-function-attribute_002c-MSP430"></a> |
| <a name="index-interrupt-function-attribute_002c-NDS32"></a> |
| <a name="index-interrupt-function-attribute_002c-RL78"></a> |
| <a name="index-interrupt-function-attribute_002c-RX"></a> |
| <a name="index-interrupt-function-attribute_002c-Visium"></a> |
| <a name="index-interrupt-function-attribute_002c-Xstormy16"></a> |
| <p>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> |
| <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> |
| <p>Note, on the ARC, you must specify the kind of interrupt to be handled |
| in a parameter to the interrupt attribute like this: |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample">void f () __attribute__ ((interrupt ("ilink1"))); |
| </pre></div> |
| |
| <p>Permissible values for this parameter are: <code>ilink1</code><!-- /@w --> and |
| <code>ilink2</code><!-- /@w -->. |
| </p> |
| <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> |
| <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: |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample">void f () __attribute__ ((interrupt ("IRQ"))); |
| </pre></div> |
| |
| <p>Permissible values for this parameter are: <code>IRQ</code>, <code>FIQ</code>, |
| <code>SWI</code>, <code>ABORT</code> and <code>UNDEF</code>. |
| </p> |
| <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> |
| <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> |
| <p>You can also use the following function attributes to modify how |
| normal functions interact with interrupt functions: |
| </p> |
| <dl compact="compact"> |
| <dt><code>critical</code></dt> |
| <dd><a name="index-critical-function-attribute_002c-MSP430"></a> |
| <p>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. |
| </p> |
| </dd> |
| <dt><code>reentrant</code></dt> |
| <dd><a name="index-reentrant-function-attribute_002c-MSP430"></a> |
| <p>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. |
| </p> |
| </dd> |
| <dt><code>wakeup</code></dt> |
| <dd><a name="index-wakeup-function-attribute_002c-MSP430"></a> |
| <p>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. |
| </p> |
| </dd> |
| </dl> |
| |
| <p>On Epiphany targets one or more optional parameters can be added like this: |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample">void __attribute__ ((interrupt ("dma0, dma1"))) universal_dma_handler (); |
| </pre></div> |
| |
| <p>Permissible values for these parameters are: <code>reset</code><!-- /@w -->, |
| <code><span class="nolinebreak">software_exception</span></code><!-- /@w -->, <code><span class="nolinebreak">page_miss</span></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 <span class="nolinebreak">ivt_entry_</span><var>name</var><!-- /@w -->. The parameter(s) may be omitted |
| entirely, in which case no interrupt vector table entry is provided. |
| </p> |
| <p>Note, on Epiphany targets, interrupts are enabled inside the function |
| unless the <code>disinterrupt</code> attribute is also specified. |
| </p> |
| <p>On Epiphany targets, you can also use the following attribute to |
| modify the behavior of an interrupt handler: |
| </p><dl compact="compact"> |
| <dt><code>forwarder_section</code></dt> |
| <dd><a name="index-forwarder_005fsection-function-attribute_002c-Epiphany"></a> |
| <p>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. |
| </p></dd> |
| </dl> |
| |
| <p>The following examples are all valid uses of these attributes on |
| Epiphany targets: |
| </p><div class="smallexample"> |
| <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></div> |
| |
| <p>On MIPS targets, you can use the following attributes to modify the behavior |
| of an interrupt handler: |
| </p><dl compact="compact"> |
| <dt><code>use_shadow_register_set</code></dt> |
| <dd><a name="index-use_005fshadow_005fregister_005fset-function-attribute_002c-MIPS"></a> |
| <p>Assume that the handler uses a shadow register set, instead of |
| the main general-purpose registers. |
| </p> |
| </dd> |
| <dt><code>keep_interrupts_masked</code></dt> |
| <dd><a name="index-keep_005finterrupts_005fmasked-function-attribute_002c-MIPS"></a> |
| <p>Keep interrupts masked for the whole function. Without this attribute, |
| GCC tries to reenable interrupts for as much of the function as it can. |
| </p> |
| </dd> |
| <dt><code>use_debug_exception_return</code></dt> |
| <dd><a name="index-use_005fdebug_005fexception_005freturn-function-attribute_002c-MIPS"></a> |
| <p>Return using the <code>deret</code> instruction. Interrupt handlers that don’t |
| have this attribute return using <code>eret</code> instead. |
| </p></dd> |
| </dl> |
| |
| <p>You can use any combination of these attributes, as shown below: |
| </p><div class="smallexample"> |
| <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></div> |
| |
| <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: |
| </p><dl compact="compact"> |
| <dt><code>nested</code></dt> |
| <dd><a name="index-nested-function-attribute_002c-NDS32"></a> |
| <p>This interrupt service routine is interruptible. |
| </p></dd> |
| <dt><code>not_nested</code></dt> |
| <dd><a name="index-not_005fnested-function-attribute_002c-NDS32"></a> |
| <p>This interrupt service routine is not interruptible. |
| </p></dd> |
| <dt><code>nested_ready</code></dt> |
| <dd><a name="index-nested_005fready-function-attribute_002c-NDS32"></a> |
| <p>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. |
| </p></dd> |
| <dt><code>save_all</code></dt> |
| <dd><a name="index-save_005fall-function-attribute_002c-NDS32"></a> |
| <p>The system will help save all registers into stack before entering |
| interrupt handler. |
| </p></dd> |
| <dt><code>partial_save</code></dt> |
| <dd><a name="index-partial_005fsave-function-attribute_002c-NDS32"></a> |
| <p>The system will help save caller registers into stack before entering |
| interrupt handler. |
| </p></dd> |
| </dl> |
| |
| <a name="index-brk_005finterrupt-function-attribute_002c-RL78"></a> |
| <p>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> |
| <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> |
| <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): |
| </p><div class="smallexample"> |
| <pre class="smallexample">void __attribute__ ((interrupt (5))) txd1_handler (); |
| </pre></div> |
| |
| <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: |
| </p><div class="smallexample"> |
| <pre class="smallexample">void __attribute__ ((interrupt (RXD1_VECT,RXD2_VECT,"dct","$default"))) |
| txd1_handler (); |
| </pre></div> |
| |
| </dd> |
| <dt><code>interrupt_handler</code></dt> |
| <dd><a name="index-interrupt_005fhandler-function-attribute_002c-Blackfin"></a> |
| <a name="index-interrupt_005fhandler-function-attribute_002c-m68k"></a> |
| <a name="index-interrupt_005fhandler-function-attribute_002c-H8_002f300"></a> |
| <a name="index-interrupt_005fhandler-function-attribute_002c-SH"></a> |
| <p>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. |
| </p> |
| </dd> |
| <dt><code>interrupt_thread</code></dt> |
| <dd><a name="index-interrupt_005fthread-function-attribute_002c-fido"></a> |
| <p>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. |
| </p> |
| </dd> |
| <dt><code>isr</code></dt> |
| <dd><a name="index-isr-function-attribute_002c-ARM"></a> |
| <p>Use this attribute on ARM to write Interrupt Service Routines. This is an |
| alias to the <code>interrupt</code> attribute above. |
| </p> |
| </dd> |
| <dt><code>kspisusp</code></dt> |
| <dd><a name="index-kspisusp-function-attribute_002c-Blackfin"></a> |
| <a name="index-User-stack-pointer-in-interrupts-on-the-Blackfin"></a> |
| <p>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. |
| </p> |
| </dd> |
| <dt><code>l1_text</code></dt> |
| <dd><a name="index-l1_005ftext-function-attribute_002c-Blackfin"></a> |
| <p>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>-mfdpic</samp>, function calls with a such function as the callee |
| or caller uses inlined PLT. |
| </p> |
| </dd> |
| <dt><code>l2</code></dt> |
| <dd><a name="index-l2-function-attribute_002c-Blackfin"></a> |
| <p>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>-mfdpic</samp>, callers of such functions use |
| an inlined PLT. |
| </p> |
| </dd> |
| <dt><code>leaf</code></dt> |
| <dd><a name="index-leaf-function-attribute"></a> |
| <p>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> |
| <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> |
| <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> |
| <p>The attribute has no effect on functions defined within the current compilation |
| unit. This is to allow easy merging of multiple compilation units into one, |
| for example, by using the link-time optimization. For this reason the |
| attribute is not allowed on types to annotate indirect calls. |
| </p> |
| </dd> |
| <dt><code>long_call</code></dt> |
| <dt><code>medium_call</code></dt> |
| <dt><code>short_call</code></dt> |
| <dd><a name="index-long_005fcall-function-attribute_002c-ARC"></a> |
| <a name="index-long_005fcall-function-attribute_002c-ARM"></a> |
| <a name="index-long_005fcall-function-attribute_002c-Epiphany"></a> |
| <a name="index-medium_005fcall-function-attribute_002c-ARC"></a> |
| <a name="index-short_005fcall-function-attribute_002c-ARC"></a> |
| <a name="index-short_005fcall-function-attribute_002c-ARM"></a> |
| <a name="index-short_005fcall-function-attribute_002c-Epiphany"></a> |
| <a name="index-indirect-calls_002c-ARC"></a> |
| <a name="index-indirect-calls_002c-ARM"></a> |
| <a name="index-indirect-calls_002c-Epiphany"></a> |
| <p>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>-mlong-calls</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>-mmedium-calls</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>BL</samp>’ |
| instruction directly. |
| </p> |
| <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. |
| </p> |
| </dd> |
| <dt><code>longcall</code></dt> |
| <dt><code>shortcall</code></dt> |
| <dd><a name="index-indirect-calls_002c-Blackfin"></a> |
| <a name="index-indirect-calls_002c-PowerPC"></a> |
| <a name="index-longcall-function-attribute_002c-Blackfin"></a> |
| <a name="index-longcall-function-attribute_002c-PowerPC"></a> |
| <a name="index-shortcall-function-attribute_002c-Blackfin"></a> |
| <a name="index-shortcall-function-attribute_002c-PowerPC"></a> |
| <p>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>-mlongcall</samp> switch and, on the RS/6000 and |
| PowerPC, the <code>#pragma longcall</code> setting. |
| </p> |
| <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. |
| </p> |
| </dd> |
| <dt><code>long_call</code></dt> |
| <dt><code>near</code></dt> |
| <dt><code>far</code></dt> |
| <dd><a name="index-indirect-calls_002c-MIPS"></a> |
| <a name="index-long_005fcall-function-attribute_002c-MIPS"></a> |
| <a name="index-near-function-attribute_002c-MIPS"></a> |
| <a name="index-far-function-attribute_002c-MIPS"></a> |
| <p>These attributes specify how a particular function is called on MIPS. |
| The attributes override the <samp>-mlong-calls</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. |
| </p> |
| </dd> |
| <dt><code>malloc</code></dt> |
| <dd><a name="index-malloc-function-attribute"></a> |
| <p>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> |
| <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. |
| </p> |
| </dd> |
| <dt><code>mips16</code></dt> |
| <dt><code>nomips16</code></dt> |
| <dd><a name="index-mips16-function-attribute_002c-MIPS"></a> |
| <a name="index-nomips16-function-attribute_002c-MIPS"></a> |
| |
| <p>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>-mips16</samp> and <samp>-mno-mips16</samp> options on the command line |
| (see <a href="MIPS-Options.html#MIPS-Options">MIPS Options</a>). |
| </p> |
| <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>). |
| </p> |
| </dd> |
| <dt><code>micromips, MIPS</code></dt> |
| <dt><code>nomicromips, MIPS</code></dt> |
| <dd><a name="index-micromips-function-attribute"></a> |
| <a name="index-nomicromips-function-attribute"></a> |
| |
| <p>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>-mmicromips</samp> and <samp>-mno-micromips</samp> options on the command line |
| (see <a href="MIPS-Options.html#MIPS-Options">MIPS Options</a>). |
| </p> |
| <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>). |
| </p> |
| </dd> |
| <dt><code>model (<var>model-name</var>)</code></dt> |
| <dd><a name="index-model-function-attribute_002c-M32R_002fD"></a> |
| <a name="index-function-addressability-on-the-M32R_002fD"></a> |
| |
| <p>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> |
| <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> |
| <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> |
| <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). |
| </p> |
| </dd> |
| <dt><code>ms_abi</code></dt> |
| <dt><code>sysv_abi</code></dt> |
| <dd><a name="index-ms_005fabi-function-attribute_002c-x86"></a> |
| <a name="index-sysv_005fabi-function-attribute_002c-x86"></a> |
| |
| <p>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> |
| <p>Note, the <code>ms_abi</code> attribute for Microsoft Windows 64-bit targets currently |
| requires the <samp>-maccumulate-outgoing-args</samp> option. |
| </p> |
| </dd> |
| <dt><code>callee_pop_aggregate_return (<var>number</var>)</code></dt> |
| <dd><a name="index-callee_005fpop_005faggregate_005freturn-function-attribute_002c-x86"></a> |
| |
| <p>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> |
| <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. |
| </p> |
| </dd> |
| <dt><code>ms_hook_prologue</code></dt> |
| <dd><a name="index-ms_005fhook_005fprologue-function-attribute_002c-x86"></a> |
| |
| <p>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. |
| </p> |
| </dd> |
| <dt><code>hotpatch (<var>halfwords-before-function-label</var>,<var>halfwords-after-function-label</var>)</code></dt> |
| <dd><a name="index-hotpatch-function-attribute_002c-S_002f390"></a> |
| |
| <p>On S/390 System z targets, you can use this function attribute to |
| make GCC generate a “hot-patching” function prologue. If the |
| <samp>-mhotpatch=</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> |
| <p>If both arguments are zero, hotpatching is disabled. |
| </p> |
| </dd> |
| <dt><code>naked</code></dt> |
| <dd><a name="index-naked-function-attribute_002c-ARM"></a> |
| <a name="index-naked-function-attribute_002c-AVR"></a> |
| <a name="index-naked-function-attribute_002c-MCORE"></a> |
| <a name="index-naked-function-attribute_002c-MSP430"></a> |
| <a name="index-naked-function-attribute_002c-NDS32"></a> |
| <a name="index-naked-function-attribute_002c-RL78"></a> |
| <a name="index-naked-function-attribute_002c-RX"></a> |
| <a name="index-naked-function-attribute_002c-SPU"></a> |
| <a name="index-function-without-prologue_002fepilogue-code"></a> |
| <p>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. |
| </p> |
| </dd> |
| <dt><code>near</code></dt> |
| <dd><a name="index-near-function-attribute_002c-MeP"></a> |
| <a name="index-functions-that-do-not-handle-memory-bank-switching-on-68HC11_002f68HC12"></a> |
| <p>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>-mtf</samp> command-line option. |
| </p> |
| </dd> |
| <dt><code>nesting</code></dt> |
| <dd><a name="index-nesting-function-attribute_002c-Blackfin"></a> |
| <a name="index-Allow-nesting-in-an-interrupt-handler-on-the-Blackfin-processor"></a> |
| <p>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. |
| </p> |
| </dd> |
| <dt><code>nmi_handler</code></dt> |
| <dd><a name="index-nmi_005fhandler-function-attribute_002c-Blackfin"></a> |
| <a name="index-NMI-handler-functions-on-the-Blackfin-processor"></a> |
| <p>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. |
| </p> |
| </dd> |
| <dt><code>nocompression</code></dt> |
| <dd><a name="index-nocompression-function-attribute_002c-MIPS"></a> |
| <p>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>-mips16</samp> and <samp>-mmicromips</samp> options on the |
| command line (see <a href="MIPS-Options.html#MIPS-Options">MIPS Options</a>). |
| </p> |
| </dd> |
| <dt><code>no_instrument_function</code></dt> |
| <dd><a name="index-no_005finstrument_005ffunction-function-attribute"></a> |
| <a name="index-finstrument_002dfunctions-1"></a> |
| <p>If <samp>-finstrument-functions</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. |
| </p> |
| </dd> |
| <dt><code>no_split_stack</code></dt> |
| <dd><a name="index-no_005fsplit_005fstack-function-attribute"></a> |
| <a name="index-fsplit_002dstack-1"></a> |
| <p>If <samp>-fsplit-stack</samp> is given, functions have a small |
| prologue which decides whether to split the stack. Functions with the |
| <code>no_split_stack</code> attribute do not have that prologue, and thus |
| may run with only a small amount of stack space available. |
| </p> |
| </dd> |
| <dt><code>stack_protect</code></dt> |
| <dd><a name="index-stack_005fprotect-function-attribute"></a> |
| <p>This function attribute make a stack protection of the function if |
| flags <samp>fstack-protector</samp> or <samp>fstack-protector-strong</samp> |
| or <samp>fstack-protector-explicit</samp> are set. |
| </p> |
| </dd> |
| <dt><code>noinline</code></dt> |
| <dd><a name="index-noinline-function-attribute"></a> |
| <p>This function attribute prevents a function from being considered for |
| inlining. |
| If the function does not have side-effects, there are optimizations |
| other than inlining that cause function calls to be optimized away, |
| although the function call is live. To keep such calls from being |
| optimized away, put |
| </p><div class="smallexample"> |
| <pre class="smallexample">asm (""); |
| </pre></div> |
| |
| <p>(see <a href="Extended-Asm.html#Extended-Asm">Extended Asm</a>) in the called function, to serve as a special |
| side-effect. |
| </p> |
| </dd> |
| <dt><code>noclone</code></dt> |
| <dd><a name="index-noclone-function-attribute"></a> |
| <p>This function attribute prevents a function from being considered for |
| cloning—a mechanism that produces specialized copies of functions |
| and which is (currently) performed by interprocedural constant |
| propagation. |
| </p> |
| </dd> |
| <dt><code>no_icf</code></dt> |
| <dd><a name="index-no_005ficf-function-attribute"></a> |
| <p>This function attribute prevents a functions from being merged with another |
| semantically equivalent function. |
| </p> |
| </dd> |
| <dt><code>nonnull (<var>arg-index</var>, …)</code></dt> |
| <dd><a name="index-nonnull-function-attribute"></a> |
| <p>The <code>nonnull</code> attribute specifies that some function parameters should |
| be non-null pointers. For instance, the declaration: |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample">extern void * |
| my_memcpy (void *dest, const void *src, size_t len) |
| __attribute__((nonnull (1, 2))); |
| </pre></div> |
| |
| <p>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>-Wnonnull</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> |
| <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: |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample">extern void * |
| my_memcpy (void *dest, const void *src, size_t len) |
| __attribute__((nonnull)); |
| </pre></div> |
| |
| </dd> |
| <dt><code>no_reorder</code></dt> |
| <dd><a name="index-no_005freorder-function-attribute"></a> |
| <p>Do not reorder functions or variables marked <code>no_reorder</code> |
| against each other or top level assembler statements the executable. |
| The actual order in the program will depend on the linker command |
| line. Static variables marked like this are also not removed. |
| This has a similar effect |
| as the <samp>-fno-toplevel-reorder</samp> option, but only applies to the |
| marked symbols. |
| </p> |
| </dd> |
| <dt><code>returns_nonnull</code></dt> |
| <dd><a name="index-returns_005fnonnull-function-attribute"></a> |
| <p>The <code>returns_nonnull</code> attribute specifies that the function |
| return value should be a non-null pointer. For instance, the declaration: |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample">extern void * |
| mymalloc (size_t len) __attribute__((returns_nonnull)); |
| </pre></div> |
| |
| <p>lets the compiler optimize callers based on the knowledge |
| that the return value will never be null. |
| </p> |
| </dd> |
| <dt><code>noreturn</code></dt> |
| <dd><a name="index-noreturn-function-attribute"></a> |
| <p>A few standard library functions, such as <code>abort</code> and <code>exit</code>, |
| cannot return. GCC knows this automatically. Some programs define |
| their own functions that never return. You can declare them |
| <code>noreturn</code> to tell the compiler this fact. For example, |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample">void fatal () __attribute__ ((noreturn)); |
| |
| void |
| fatal (/* <span class="roman">…</span> */) |
| { |
| /* <span class="roman">…</span> */ /* <span class="roman">Print error message.</span> */ /* <span class="roman">…</span> */ |
| exit (1); |
| } |
| </pre></div> |
| |
| <p>The <code>noreturn</code> keyword tells the compiler to assume that |
| <code>fatal</code> cannot return. It can then optimize without regard to what |
| would happen if <code>fatal</code> ever did return. This makes slightly |
| better code. More importantly, it helps avoid spurious warnings of |
| uninitialized variables. |
| </p> |
| <p>The <code>noreturn</code> keyword does not affect the exceptional path when that |
| applies: a <code>noreturn</code>-marked function may still return to the caller |
| by throwing an exception or calling <code>longjmp</code>. |
| </p> |
| <p>Do not assume that registers saved by the calling function are |
| restored before calling the <code>noreturn</code> function. |
| </p> |
| <p>It does not make sense for a <code>noreturn</code> function to have a return |
| type other than <code>void</code>. |
| </p> |
| </dd> |
| <dt><code>nothrow</code></dt> |
| <dd><a name="index-nothrow-function-attribute"></a> |
| <p>The <code>nothrow</code> attribute is used to inform the compiler that a |
| function cannot throw an exception. For example, most functions in |
| the standard C library can be guaranteed not to throw an exception |
| with the notable exceptions of <code>qsort</code> and <code>bsearch</code> that |
| take function pointer arguments. |
| </p> |
| </dd> |
| <dt><code>nosave_low_regs</code></dt> |
| <dd><a name="index-nosave_005flow_005fregs-function-attribute_002c-SH"></a> |
| <p>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. |
| </p> |
| </dd> |
| <dt><code>optimize</code></dt> |
| <dd><a name="index-optimize-function-attribute"></a> |
| <p>The <code>optimize</code> attribute is used to specify that a function is to |
| be compiled with different optimization options than specified on the |
| command line. 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>#pragma GCC optimize</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>#pragma GCC optimize</samp>’ pragma. |
| </p> |
| <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. |
| </p> |
| </dd> |
| <dt><code>OS_main</code></dt> |
| <dt><code>OS_task</code></dt> |
| <dd><a name="index-OS_005fmain-function-attribute_002c-AVR"></a> |
| <a name="index-OS_005ftask-function-attribute_002c-AVR"></a> |
| <p>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> |
| <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> |
| <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> |
| <p>The differences to the <code>naked</code> function attribute are: |
| </p><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><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. |
| </li></ul> |
| |
| </dd> |
| <dt><code>pcs</code></dt> |
| <dd><a name="index-pcs-function-attribute_002c-ARM"></a> |
| |
| <p>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> |
| <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, |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample">/* Argument passed in r0, and result returned in r0+r1. */ |
| double f2d (float) __attribute__((pcs("aapcs"))); |
| </pre></div> |
| |
| <p>Variadic functions always use the <code>"aapcs"</code> calling convention and |
| the compiler rejects attempts to specify an alternative. |
| </p> |
| </dd> |
| <dt><code>pure</code></dt> |
| <dd><a name="index-pure-function-attribute"></a> |
| <p>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, |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample">int square (int) __attribute__ ((pure)); |
| </pre></div> |
| |
| <p>says that the hypothetical function <code>square</code> is safe to call |
| fewer times than the program says. |
| </p> |
| <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). |
| </p> |
| </dd> |
| <dt><code>hot</code></dt> |
| <dd><a name="index-hot-function-attribute"></a> |
| <p>The <code>hot</code> attribute on a function is used to inform the compiler that |
| the function is a hot spot of the compiled program. The function is |
| optimized more aggressively and on many targets it is placed into a special |
| subsection of the text section so all hot functions appear close together, |
| improving locality. |
| </p> |
| <p>When profile feedback is available, via <samp>-fprofile-use</samp>, hot functions |
| are automatically detected and this attribute is ignored. |
| </p> |
| </dd> |
| <dt><code>cold</code></dt> |
| <dd><a name="index-cold-function-attribute"></a> |
| <p>The <code>cold</code> attribute on functions is used to inform the compiler that |
| the function is unlikely to be executed. The function is optimized for |
| size rather than speed and on many targets it is placed into a special |
| subsection of the text section so all cold functions appear close together, |
| improving code locality of non-cold parts of program. The paths leading |
| to calls of cold functions within code are marked as unlikely by the branch |
| prediction mechanism. It is thus useful to mark functions used to handle |
| unlikely conditions, such as <code>perror</code>, as cold to improve optimization |
| of hot functions that do call marked functions in rare occasions. |
| </p> |
| <p>When profile feedback is available, via <samp>-fprofile-use</samp>, cold functions |
| are automatically detected and this attribute is ignored. |
| </p> |
| </dd> |
| <dt><code>no_sanitize_address</code></dt> |
| <dt><code>no_address_safety_analysis</code></dt> |
| <dd><a name="index-no_005fsanitize_005faddress-function-attribute"></a> |
| <p>The <code>no_sanitize_address</code> attribute on functions is used |
| to inform the compiler that it should not instrument memory accesses |
| in the function when compiling with the <samp>-fsanitize=address</samp> option. |
| The <code>no_address_safety_analysis</code> is a deprecated alias of the |
| <code>no_sanitize_address</code> attribute, new code should use |
| <code>no_sanitize_address</code>. |
| </p> |
| </dd> |
| <dt><code>no_sanitize_thread</code></dt> |
| <dd><a name="index-no_005fsanitize_005fthread-function-attribute"></a> |
| <p>The <code>no_sanitize_thread</code> attribute on functions is used |
| to inform the compiler that it should not instrument memory accesses |
| in the function when compiling with the <samp>-fsanitize=thread</samp> option. |
| </p> |
| </dd> |
| <dt><code>no_sanitize_undefined</code></dt> |
| <dd><a name="index-no_005fsanitize_005fundefined-function-attribute"></a> |
| <p>The <code>no_sanitize_undefined</code> attribute on functions is used |
| to inform the compiler that it should not check for undefined behavior |
| in the function when compiling with the <samp>-fsanitize=undefined</samp> option. |
| </p> |
| </dd> |
| <dt><code>bnd_legacy</code></dt> |
| <dd><a name="index-bnd_005flegacy-function-attribute"></a> |
| <a name="index-Pointer-Bounds-Checker-attributes"></a> |
| <p>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>-fcheck-pointer-bounds</samp> option. |
| </p> |
| </dd> |
| <dt><code>bnd_instrument</code></dt> |
| <dd><a name="index-bnd_005finstrument-function-attribute"></a> |
| <p>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>-fchkp-instrument-marked-only</samp> option. |
| </p> |
| </dd> |
| <dt><code>regparm (<var>number</var>)</code></dt> |
| <dd><a name="index-regparm-function-attribute_002c-x86"></a> |
| <a name="index-functions-that-are-passed-arguments-in-registers-on-x86_002d32-1"></a> |
| <p>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> |
| <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.) |
| </p> |
| </dd> |
| <dt><code>reset</code></dt> |
| <dd><a name="index-reset-function-attribute_002c-NDS32"></a> |
| <a name="index-reset-handler-functions"></a> |
| <p>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: |
| </p><dl compact="compact"> |
| <dt><code>nmi</code></dt> |
| <dd><a name="index-nmi-function-attribute_002c-NDS32"></a> |
| <p>Provide a user-defined function to handle NMI exception. |
| </p></dd> |
| <dt><code>warm</code></dt> |
| <dd><a name="index-warm-function-attribute_002c-NDS32"></a> |
| <p>Provide a user-defined function to handle warm reset exception. |
| </p></dd> |
| </dl> |
| |
| </dd> |
| <dt><code>sseregparm</code></dt> |
| <dd><a name="index-sseregparm-function-attribute_002c-x86"></a> |
| <p>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. |
| </p> |
| </dd> |
| <dt><code>force_align_arg_pointer</code></dt> |
| <dd><a name="index-force_005falign_005farg_005fpointer-function-attribute_002c-x86"></a> |
| <p>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. |
| </p> |
| </dd> |
| <dt><code>renesas</code></dt> |
| <dd><a name="index-renesas-function-attribute_002c-SH"></a> |
| <p>On SH targets this attribute specifies that the function or struct follows the |
| Renesas ABI. |
| </p> |
| </dd> |
| <dt><code>resbank</code></dt> |
| <dd><a name="index-resbank-function-attribute_002c-SH"></a> |
| <p>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> |
| <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. |
| </p> |
| </dd> |
| <dt><code>returns_twice</code></dt> |
| <dd><a name="index-returns_005ftwice-function-attribute"></a> |
| <p>The <code>returns_twice</code> attribute tells the compiler that a function may |
| return more than one time. The compiler ensures that all registers |
| are dead before calling such a function and emits a warning about |
| the variables that may be clobbered after the second return from the |
| function. Examples of such functions are <code>setjmp</code> and <code>vfork</code>. |
| The <code>longjmp</code>-like counterpart of such function, if any, might need |
| to be marked with the <code>noreturn</code> attribute. |
| </p> |
| </dd> |
| <dt><code>saveall</code></dt> |
| <dd><a name="index-saveall-function-attribute_002c-Blackfin"></a> |
| <a name="index-saveall-function-attribute_002c-H8_002f300"></a> |
| <a name="index-save-all-registers-on-the-Blackfin_002c-H8_002f300_002c-H8_002f300H_002c-and-H8S"></a> |
| <p>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. |
| </p> |
| </dd> |
| <dt><code>save_volatiles</code></dt> |
| <dd><a name="index-save_005fvolatiles-function-attribute_002c-MicroBlaze"></a> |
| <p>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. |
| </p> |
| </dd> |
| <dt><code>break_handler</code></dt> |
| <dd><a name="index-break_005fhandler-function-attribute_002c-MicroBlaze"></a> |
| <a name="index-break-handler-functions"></a> |
| <p>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>. |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample">void f () __attribute__ ((break_handler)); |
| </pre></div> |
| |
| </dd> |
| <dt><code>section ("<var>section-name</var>")</code></dt> |
| <dd><a name="index-section-function-attribute"></a> |
| <p>Normally, the compiler places the code it generates in the <code>text</code> section. |
| Sometimes, however, you need additional sections, or you need certain |
| particular functions to appear in special sections. The <code>section</code> |
| attribute specifies that a function lives in a particular section. |
| For example, the declaration: |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample">extern void foobar (void) __attribute__ ((section ("bar"))); |
| </pre></div> |
| |
| <p>puts the function <code>foobar</code> in the <code>bar</code> section. |
| </p> |
| <p>Some file formats do not support arbitrary sections so the <code>section</code> |
| attribute is not available on all platforms. |
| If you need to map the entire contents of a module to a particular |
| section, consider using the facilities of the linker instead. |
| </p> |
| </dd> |
| <dt><code>sentinel</code></dt> |
| <dd><a name="index-sentinel-function-attribute"></a> |
| <p>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. |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample">__attribute__ ((sentinel)) |
| is equivalent to |
| __attribute__ ((sentinel(0))) |
| </pre></div> |
| |
| <p>The attribute is automatically set with a position of 0 for the built-in |
| functions <code>execl</code> and <code>execlp</code>. The built-in function |
| <code>execle</code> has the attribute set with a position of 1. |
| </p> |
| <p>A valid <code>NULL</code> in this context is defined as zero with any 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> |
| <p>The warnings for missing or incorrect sentinels are enabled with |
| <samp>-Wformat</samp>. |
| </p> |
| </dd> |
| <dt><code>short_call</code></dt> |
| <dd><p>See <code>long_call</code>. |
| </p> |
| </dd> |
| <dt><code>shortcall</code></dt> |
| <dd><p>See <code>longcall</code>. |
| </p> |
| </dd> |
| <dt><code>signal</code></dt> |
| <dd><a name="index-signal-function-attribute_002c-AVR"></a> |
| <p>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> |
| <p>See also the <code>interrupt</code> function attribute. |
| </p> |
| <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> |
| <p>If both <code>signal</code> and <code>interrupt</code> are specified for the same |
| function, <code>signal</code> is silently ignored. |
| </p> |
| </dd> |
| <dt><code>sp_switch</code></dt> |
| <dd><a name="index-sp_005fswitch-function-attribute_002c-SH"></a> |
| <p>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. |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample">void *alt_stack; |
| void f () __attribute__ ((interrupt_handler, |
| sp_switch ("alt_stack"))); |
| </pre></div> |
| |
| </dd> |
| <dt><code>stdcall</code></dt> |
| <dd><a name="index-stdcall-function-attribute_002c-x86_002d32"></a> |
| <a name="index-functions-that-pop-the-argument-stack-on-x86_002d32-3"></a> |
| <p>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. |
| </p> |
| </dd> |
| <dt><code>syscall_linkage</code></dt> |
| <dd><a name="index-syscall_005flinkage-function-attribute_002c-IA_002d64"></a> |
| <p>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. |
| </p> |
| </dd> |
| <dt><code>target</code></dt> |
| <dd><a name="index-target-function-attribute"></a> |
| <p>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>#pragma GCC target</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>#pragma GCC target</samp>’ pragma. |
| </p> |
| <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>-msse4.1</samp> and |
| <samp>-march=core2</samp> options, and the second function with |
| <samp>-msse4a</samp> and <samp>-march=amdfam10</samp> options. It is up to 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). |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample">int core2_func (void) __attribute__ ((__target__ ("arch=core2"))); |
| int sse3_func (void) __attribute__ ((__target__ ("sse3"))); |
| </pre></div> |
| |
| <p>You can either use multiple |
| strings to specify multiple options, or separate the options |
| with a comma (‘<samp>,</samp>’). |
| </p> |
| <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> |
| <p>On the x86, the following options are allowed: |
| </p> |
| <dl compact="compact"> |
| <dt>‘<samp>abm</samp>’</dt> |
| <dt>‘<samp>no-abm</samp>’</dt> |
| <dd><a name="index-target_0028_0022abm_0022_0029-function-attribute_002c-x86"></a> |
| <p>Enable/disable the generation of the advanced bit instructions. |
| </p> |
| </dd> |
| <dt>‘<samp>aes</samp>’</dt> |
| <dt>‘<samp>no-aes</samp>’</dt> |
| <dd><a name="index-target_0028_0022aes_0022_0029-function-attribute_002c-x86"></a> |
| <p>Enable/disable the generation of the AES instructions. |
| </p> |
| </dd> |
| <dt>‘<samp>default</samp>’</dt> |
| <dd><a name="index-target_0028_0022default_0022_0029-function-attribute_002c-x86"></a> |
| <p>See <a href="Function-Multiversioning.html#Function-Multiversioning">Function Multiversioning</a>, where it is used to specify the |
| default function version. |
| </p> |
| </dd> |
| <dt>‘<samp>mmx</samp>’</dt> |
| <dt>‘<samp>no-mmx</samp>’</dt> |
| <dd><a name="index-target_0028_0022mmx_0022_0029-function-attribute_002c-x86"></a> |
| <p>Enable/disable the generation of the MMX instructions. |
| </p> |
| </dd> |
| <dt>‘<samp>pclmul</samp>’</dt> |
| <dt>‘<samp>no-pclmul</samp>’</dt> |
| <dd><a name="index-target_0028_0022pclmul_0022_0029-function-attribute_002c-x86"></a> |
| <p>Enable/disable the generation of the PCLMUL instructions. |
| </p> |
| </dd> |
| <dt>‘<samp>popcnt</samp>’</dt> |
| <dt>‘<samp>no-popcnt</samp>’</dt> |
| <dd><a name="index-target_0028_0022popcnt_0022_0029-function-attribute_002c-x86"></a> |
| <p>Enable/disable the generation of the POPCNT instruction. |
| </p> |
| </dd> |
| <dt>‘<samp>sse</samp>’</dt> |
| <dt>‘<samp>no-sse</samp>’</dt> |
| <dd><a name="index-target_0028_0022sse_0022_0029-function-attribute_002c-x86"></a> |
| <p>Enable/disable the generation of the SSE instructions. |
| </p> |
| </dd> |
| <dt>‘<samp>sse2</samp>’</dt> |
| <dt>‘<samp>no-sse2</samp>’</dt> |
| <dd><a name="index-target_0028_0022sse2_0022_0029-function-attribute_002c-x86"></a> |
| <p>Enable/disable the generation of the SSE2 instructions. |
| </p> |
| </dd> |
| <dt>‘<samp>sse3</samp>’</dt> |
| <dt>‘<samp>no-sse3</samp>’</dt> |
| <dd><a name="index-target_0028_0022sse3_0022_0029-function-attribute_002c-x86"></a> |
| <p>Enable/disable the generation of the SSE3 instructions. |
| </p> |
| </dd> |
| <dt>‘<samp>sse4</samp>’</dt> |
| <dt>‘<samp>no-sse4</samp>’</dt> |
| <dd><a name="index-target_0028_0022sse4_0022_0029-function-attribute_002c-x86"></a> |
| <p>Enable/disable the generation of the SSE4 instructions (both SSE4.1 |
| and SSE4.2). |
| </p> |
| </dd> |
| <dt>‘<samp>sse4.1</samp>’</dt> |
| <dt>‘<samp>no-sse4.1</samp>’</dt> |
| <dd><a name="index-target_0028_0022sse4_002e1_0022_0029-function-attribute_002c-x86"></a> |
| <p>Enable/disable the generation of the sse4.1 instructions. |
| </p> |
| </dd> |
| <dt>‘<samp>sse4.2</samp>’</dt> |
| <dt>‘<samp>no-sse4.2</samp>’</dt> |
| <dd><a name="index-target_0028_0022sse4_002e2_0022_0029-function-attribute_002c-x86"></a> |
| <p>Enable/disable the generation of the sse4.2 instructions. |
| </p> |
| </dd> |
| <dt>‘<samp>sse4a</samp>’</dt> |
| <dt>‘<samp>no-sse4a</samp>’</dt> |
| <dd><a name="index-target_0028_0022sse4a_0022_0029-function-attribute_002c-x86"></a> |
| <p>Enable/disable the generation of the SSE4A instructions. |
| </p> |
| </dd> |
| <dt>‘<samp>fma4</samp>’</dt> |
| <dt>‘<samp>no-fma4</samp>’</dt> |
| <dd><a name="index-target_0028_0022fma4_0022_0029-function-attribute_002c-x86"></a> |
| <p>Enable/disable the generation of the FMA4 instructions. |
| </p> |
| </dd> |
| <dt>‘<samp>xop</samp>’</dt> |
| <dt>‘<samp>no-xop</samp>’</dt> |
| <dd><a name="index-target_0028_0022xop_0022_0029-function-attribute_002c-x86"></a> |
| <p>Enable/disable the generation of the XOP instructions. |
| </p> |
| </dd> |
| <dt>‘<samp>lwp</samp>’</dt> |
| <dt>‘<samp>no-lwp</samp>’</dt> |
| <dd><a name="index-target_0028_0022lwp_0022_0029-function-attribute_002c-x86"></a> |
| <p>Enable/disable the generation of the LWP instructions. |
| </p> |
| </dd> |
| <dt>‘<samp>ssse3</samp>’</dt> |
| <dt>‘<samp>no-ssse3</samp>’</dt> |
| <dd><a name="index-target_0028_0022ssse3_0022_0029-function-attribute_002c-x86"></a> |
| <p>Enable/disable the generation of the SSSE3 instructions. |
| </p> |
| </dd> |
| <dt>‘<samp>cld</samp>’</dt> |
| <dt>‘<samp>no-cld</samp>’</dt> |
| <dd><a name="index-target_0028_0022cld_0022_0029-function-attribute_002c-x86"></a> |
| <p>Enable/disable the generation of the CLD before string moves. |
| </p> |
| </dd> |
| <dt>‘<samp>fancy-math-387</samp>’</dt> |
| <dt>‘<samp>no-fancy-math-387</samp>’</dt> |
| <dd><a name="index-target_0028_0022fancy_002dmath_002d387_0022_0029-function-attribute_002c-x86"></a> |
| <p>Enable/disable the generation of the <code>sin</code>, <code>cos</code>, and |
| <code>sqrt</code> instructions on the 387 floating-point unit. |
| </p> |
| </dd> |
| <dt>‘<samp>fused-madd</samp>’</dt> |
| <dt>‘<samp>no-fused-madd</samp>’</dt> |
| <dd><a name="index-target_0028_0022fused_002dmadd_0022_0029-function-attribute_002c-x86"></a> |
| <p>Enable/disable the generation of the fused multiply/add instructions. |
| </p> |
| </dd> |
| <dt>‘<samp>ieee-fp</samp>’</dt> |
| <dt>‘<samp>no-ieee-fp</samp>’</dt> |
| <dd><a name="index-target_0028_0022ieee_002dfp_0022_0029-function-attribute_002c-x86"></a> |
| <p>Enable/disable the generation of floating point that depends on IEEE arithmetic. |
| </p> |
| </dd> |
| <dt>‘<samp>inline-all-stringops</samp>’</dt> |
| <dt>‘<samp>no-inline-all-stringops</samp>’</dt> |
| <dd><a name="index-target_0028_0022inline_002dall_002dstringops_0022_0029-function-attribute_002c-x86"></a> |
| <p>Enable/disable inlining of string operations. |
| </p> |
| </dd> |
| <dt>‘<samp>inline-stringops-dynamically</samp>’</dt> |
| <dt>‘<samp>no-inline-stringops-dynamically</samp>’</dt> |
| <dd><a name="index-target_0028_0022inline_002dstringops_002ddynamically_0022_0029-function-attribute_002c-x86"></a> |
| <p>Enable/disable the generation of the inline code to do small string |
| operations and calling the library routines for large operations. |
| </p> |
| </dd> |
| <dt>‘<samp>align-stringops</samp>’</dt> |
| <dt>‘<samp>no-align-stringops</samp>’</dt> |
| <dd><a name="index-target_0028_0022align_002dstringops_0022_0029-function-attribute_002c-x86"></a> |
| <p>Do/do not align destination of inlined string operations. |
| </p> |
| </dd> |
| <dt>‘<samp>recip</samp>’</dt> |
| <dt>‘<samp>no-recip</samp>’</dt> |
| <dd><a name="index-target_0028_0022recip_0022_0029-function-attribute_002c-x86"></a> |
| <p>Enable/disable the generation of RCPSS, RCPPS, RSQRTSS and RSQRTPS |
| instructions followed an additional Newton-Raphson step instead of |
| doing a floating-point division. |
| </p> |
| </dd> |
| <dt>‘<samp>arch=<var>ARCH</var></samp>’</dt> |
| <dd><a name="index-target_0028_0022arch_003dARCH_0022_0029-function-attribute_002c-x86"></a> |
| <p>Specify the architecture to generate code for in compiling the function. |
| </p> |
| </dd> |
| <dt>‘<samp>tune=<var>TUNE</var></samp>’</dt> |
| <dd><a name="index-target_0028_0022tune_003dTUNE_0022_0029-function-attribute_002c-x86"></a> |
| <p>Specify the architecture to tune for in compiling the function. |
| </p> |
| </dd> |
| <dt>‘<samp>fpmath=<var>FPMATH</var></samp>’</dt> |
| <dd><a name="index-target_0028_0022fpmath_003dFPMATH_0022_0029-function-attribute_002c-x86"></a> |
| <p>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. |
| </p></dd> |
| </dl> |
| |
| <p>On the PowerPC, the following options are allowed: |
| </p> |
| <dl compact="compact"> |
| <dt>‘<samp>altivec</samp>’</dt> |
| <dt>‘<samp>no-altivec</samp>’</dt> |
| <dd><a name="index-target_0028_0022altivec_0022_0029-function-attribute_002c-PowerPC"></a> |
| <p>Generate code that uses (does not use) AltiVec instructions. In |
| 32-bit code, you cannot enable AltiVec instructions unless |
| <samp>-mabi=altivec</samp> is used on the command line. |
| </p> |
| </dd> |
| <dt>‘<samp>cmpb</samp>’</dt> |
| <dt>‘<samp>no-cmpb</samp>’</dt> |
| <dd><a name="index-target_0028_0022cmpb_0022_0029-function-attribute_002c-PowerPC"></a> |
| <p>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. |
| </p> |
| </dd> |
| <dt>‘<samp>dlmzb</samp>’</dt> |
| <dt>‘<samp>no-dlmzb</samp>’</dt> |
| <dd><a name="index-target_0028_0022dlmzb_0022_0029-function-attribute_002c-PowerPC"></a> |
| <p>Generate code that uses (does not use) the string-search ‘<samp>dlmzb</samp>’ |
| instruction on the IBM 405, 440, 464 and 476 processors. This instruction is |
| generated by default when targeting those processors. |
| </p> |
| </dd> |
| <dt>‘<samp>fprnd</samp>’</dt> |
| <dt>‘<samp>no-fprnd</samp>’</dt> |
| <dd><a name="index-target_0028_0022fprnd_0022_0029-function-attribute_002c-PowerPC"></a> |
| <p>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. |
| </p> |
| </dd> |
| <dt>‘<samp>hard-dfp</samp>’</dt> |
| <dt>‘<samp>no-hard-dfp</samp>’</dt> |
| <dd><a name="index-target_0028_0022hard_002ddfp_0022_0029-function-attribute_002c-PowerPC"></a> |
| <p>Generate code that uses (does not use) the decimal floating-point |
| instructions implemented on some POWER processors. |
| </p> |
| </dd> |
| <dt>‘<samp>isel</samp>’</dt> |
| <dt>‘<samp>no-isel</samp>’</dt> |
| <dd><a name="index-target_0028_0022isel_0022_0029-function-attribute_002c-PowerPC"></a> |
| <p>Generate code that uses (does not use) ISEL instruction. |
| </p> |
| </dd> |
| <dt>‘<samp>mfcrf</samp>’</dt> |
| <dt>‘<samp>no-mfcrf</samp>’</dt> |
| <dd><a name="index-target_0028_0022mfcrf_0022_0029-function-attribute_002c-PowerPC"></a> |
| <p>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. |
| </p> |
| </dd> |
| <dt>‘<samp>mfpgpr</samp>’</dt> |
| <dt>‘<samp>no-mfpgpr</samp>’</dt> |
| <dd><a name="index-target_0028_0022mfpgpr_0022_0029-function-attribute_002c-PowerPC"></a> |
| <p>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. |
| </p> |
| </dd> |
| <dt>‘<samp>mulhw</samp>’</dt> |
| <dt>‘<samp>no-mulhw</samp>’</dt> |
| <dd><a name="index-target_0028_0022mulhw_0022_0029-function-attribute_002c-PowerPC"></a> |
| <p>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. |
| </p> |
| </dd> |
| <dt>‘<samp>multiple</samp>’</dt> |
| <dt>‘<samp>no-multiple</samp>’</dt> |
| <dd><a name="index-target_0028_0022multiple_0022_0029-function-attribute_002c-PowerPC"></a> |
| <p>Generate code that uses (does not use) the load multiple word |
| instructions and the store multiple word instructions. |
| </p> |
| </dd> |
| <dt>‘<samp>update</samp>’</dt> |
| <dt>‘<samp>no-update</samp>’</dt> |
| <dd><a name="index-target_0028_0022update_0022_0029-function-attribute_002c-PowerPC"></a> |
| <p>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. |
| </p> |
| </dd> |
| <dt>‘<samp>popcntb</samp>’</dt> |
| <dt>‘<samp>no-popcntb</samp>’</dt> |
| <dd><a name="index-target_0028_0022popcntb_0022_0029-function-attribute_002c-PowerPC"></a> |
| <p>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. |
| </p> |
| </dd> |
| <dt>‘<samp>popcntd</samp>’</dt> |
| <dt>‘<samp>no-popcntd</samp>’</dt> |
| <dd><a name="index-target_0028_0022popcntd_0022_0029-function-attribute_002c-PowerPC"></a> |
| <p>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. |
| </p> |
| </dd> |
| <dt>‘<samp>powerpc-gfxopt</samp>’</dt> |
| <dt>‘<samp>no-powerpc-gfxopt</samp>’</dt> |
| <dd><a name="index-target_0028_0022powerpc_002dgfxopt_0022_0029-function-attribute_002c-PowerPC"></a> |
| <p>Generate code that uses (does not use) the optional PowerPC |
| architecture instructions in the Graphics group, including |
| floating-point select. |
| </p> |
| </dd> |
| <dt>‘<samp>powerpc-gpopt</samp>’</dt> |
| <dt>‘<samp>no-powerpc-gpopt</samp>’</dt> |
| <dd><a name="index-target_0028_0022powerpc_002dgpopt_0022_0029-function-attribute_002c-PowerPC"></a> |
| <p>Generate code that uses (does not use) the optional PowerPC |
| architecture instructions in the General Purpose group, including |
| floating-point square root. |
| </p> |
| </dd> |
| <dt>‘<samp>recip-precision</samp>’</dt> |
| <dt>‘<samp>no-recip-precision</samp>’</dt> |
| <dd><a name="index-target_0028_0022recip_002dprecision_0022_0029-function-attribute_002c-PowerPC"></a> |
| <p>Assume (do not assume) that the reciprocal estimate instructions |
| provide higher-precision estimates than is mandated by the PowerPC |
| ABI. |
| </p> |
| </dd> |
| <dt>‘<samp>string</samp>’</dt> |
| <dt>‘<samp>no-string</samp>’</dt> |
| <dd><a name="index-target_0028_0022string_0022_0029-function-attribute_002c-PowerPC"></a> |
| <p>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. |
| </p> |
| </dd> |
| <dt>‘<samp>vsx</samp>’</dt> |
| <dt>‘<samp>no-vsx</samp>’</dt> |
| <dd><a name="index-target_0028_0022vsx_0022_0029-function-attribute_002c-PowerPC"></a> |
| <p>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>-mabi=altivec</samp> is used on the command line. |
| </p> |
| </dd> |
| <dt>‘<samp>friz</samp>’</dt> |
| <dt>‘<samp>no-friz</samp>’</dt> |
| <dd><a name="index-target_0028_0022friz_0022_0029-function-attribute_002c-PowerPC"></a> |
| <p>Generate (do not generate) the <code>friz</code> instruction when the |
| <samp>-funsafe-math-optimizations</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. |
| </p> |
| </dd> |
| <dt>‘<samp>avoid-indexed-addresses</samp>’</dt> |
| <dt>‘<samp>no-avoid-indexed-addresses</samp>’</dt> |
| <dd><a name="index-target_0028_0022avoid_002dindexed_002daddresses_0022_0029-function-attribute_002c-PowerPC"></a> |
| <p>Generate code that tries to avoid (not avoid) the use of indexed load |
| or store instructions. |
| </p> |
| </dd> |
| <dt>‘<samp>paired</samp>’</dt> |
| <dt>‘<samp>no-paired</samp>’</dt> |
| <dd><a name="index-target_0028_0022paired_0022_0029-function-attribute_002c-PowerPC"></a> |
| <p>Generate code that uses (does not use) the generation of PAIRED simd |
| instructions. |
| </p> |
| </dd> |
| <dt>‘<samp>longcall</samp>’</dt> |
| <dt>‘<samp>no-longcall</samp>’</dt> |
| <dd><a name="index-target_0028_0022longcall_0022_0029-function-attribute_002c-PowerPC"></a> |
| <p>Generate code that assumes (does not assume) that all calls are far |
| away so that a longer more expensive calling sequence is required. |
| </p> |
| </dd> |
| <dt>‘<samp>cpu=<var>CPU</var></samp>’</dt> |
| <dd><a name="index-target_0028_0022cpu_003dCPU_0022_0029-function-attribute_002c-PowerPC"></a> |
| <p>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>-mabi=altivec</samp> option on the command line. |
| </p> |
| </dd> |
| <dt>‘<samp>tune=<var>TUNE</var></samp>’</dt> |
| <dd><a name="index-target_0028_0022tune_003dTUNE_0022_0029-function-attribute_002c-PowerPC"></a> |
| <p>Specify the architecture to tune for when compiling the function. If |
| you do not specify the <code>target("tune=<var>TUNE</var>")</code> attribute and |
| you do specify the <code>target("cpu=<var>CPU</var>")</code> attribute, |
| compilation tunes for the <var>CPU</var> architecture, and not the |
| default tuning specified on the command line. |
| </p></dd> |
| </dl> |
| |
| <p>When compiling for Nios II, the following options are allowed: |
| </p> |
| <dl compact="compact"> |
| <dt>‘<samp>custom-<var>insn</var>=<var>N</var></samp>’</dt> |
| <dt>‘<samp>no-custom-<var>insn</var></samp>’</dt> |
| <dd><a name="index-target_0028_0022custom_002dinsn_003dN_0022_0029-function-attribute_002c-Nios-II"></a> |
| <a name="index-target_0028_0022no_002dcustom_002dinsn_0022_0029-function-attribute_002c-Nios-II"></a> |
| <p>Each ‘<samp>custom-<var>insn</var>=<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>no-custom-<var>insn</var></samp>’ locally inhibits use of |
| the custom instruction <var>insn</var>. |
| These target attributes correspond to the |
| <samp>-mcustom-<var>insn</var>=<var>N</var></samp> and <samp>-mno-custom-<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. |
| </p> |
| </dd> |
| <dt>‘<samp>custom-fpu-cfg=<var>name</var></samp>’</dt> |
| <dd><a name="index-target_0028_0022custom_002dfpu_002dcfg_003dname_0022_0029-function-attribute_002c-Nios-II"></a> |
| <p>This attribute corresponds to the <samp>-mcustom-fpu-cfg=<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. |
| </p></dd> |
| </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>. |
| </p> |
| </dd> |
| <dt><code>trap_exit</code></dt> |
| <dd><a name="index-trap_005fexit-function-attribute_002c-SH"></a> |
| <p>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. |
| </p> |
| </dd> |
| <dt><code>trapa_handler</code></dt> |
| <dd><a name="index-trapa_005fhandler-function-attribute_002c-SH"></a> |
| <p>On SH targets this function attribute is similar to <code>interrupt_handler</code> |
| but it does not save and restore all registers. |
| </p> |
| </dd> |
| <dt><code>unused</code></dt> |
| <dd><a name="index-unused-function-attribute"></a> |
| <p>This attribute, attached to a function, means that the function is meant |
| to be possibly unused. GCC does not produce a warning for this |
| function. |
| </p> |
| </dd> |
| <dt><code>used</code></dt> |
| <dd><a name="index-used-function-attribute"></a> |
| <p>This attribute, attached to a function, means that code must be emitted |
| for the function even if it appears that the function is not referenced. |
| This is useful, for example, when the function is referenced only in |
| inline assembly. |
| </p> |
| <p>When applied to a member function of a C++ class template, the |
| attribute also means that the function is instantiated if the |
| class itself is instantiated. |
| </p> |
| </dd> |
| <dt><code>vector</code></dt> |
| <dd><a name="index-vector-function-attribute_002c-RX"></a> |
| <p>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. |
| </p> |
| </dd> |
| <dt><code>version_id</code></dt> |
| <dd><a name="index-version_005fid-function-attribute_002c-IA_002d64"></a> |
| <p>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. |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample">extern int foo () __attribute__((version_id ("20040821"))); |
| </pre></div> |
| |
| <p>Calls to <var>foo</var> are mapped to calls to <var>foo{20040821}</var>. |
| </p> |
| </dd> |
| <dt><code>visibility ("<var>visibility_type</var>")</code></dt> |
| <dd><a name="index-visibility-function-attribute"></a> |
| <p>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. |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample">void __attribute__ ((visibility ("protected"))) |
| f () { /* <span class="roman">Do something.</span> */; } |
| int i __attribute__ ((visibility ("hidden"))); |
| </pre></div> |
| |
| <p>The possible values of <var>visibility_type</var> correspond to the |
| visibility settings in the ELF gABI. |
| </p> |
| <dl compact="compact"> |
| <dt><em>default</em></dt> |
| <dd><p>Default visibility is the normal case for the object file format. |
| This value is available for the visibility attribute to override other |
| options that may change the assumed visibility of entities. |
| </p> |
| <p>On ELF, default visibility means that the declaration is visible to other |
| modules and, in shared libraries, means that the declared entity may be |
| overridden. |
| </p> |
| <p>On Darwin, default visibility means that the declaration is visible to |
| other modules. |
| </p> |
| <p>Default visibility corresponds to “external linkage” in the language. |
| </p> |
| </dd> |
| <dt><em>hidden</em></dt> |
| <dd><p>Hidden visibility indicates that the entity declared has a new |
| form of linkage, which we call “hidden linkage”. Two |
| declarations of an object with hidden linkage refer to the same object |
| if they are in the same shared object. |
| </p> |
| </dd> |
| <dt><em>internal</em></dt> |
| <dd><p>Internal visibility is like hidden visibility, but with additional |
| processor specific semantics. Unless otherwise specified by the |
| psABI, GCC defines internal visibility to mean that a function is |
| <em>never</em> called from another module. Compare this with hidden |
| functions which, while they cannot be referenced directly by other |
| modules, can be referenced indirectly via function pointers. By |
| indicating that a function cannot be called from outside the module, |
| GCC may for instance omit the load of a PIC register since it is known |
| that the calling function loaded the correct value. |
| </p> |
| </dd> |
| <dt><em>protected</em></dt> |
| <dd><p>Protected visibility is like default visibility except that it |
| indicates that references within the defining module bind to the |
| definition in that module. That is, the declared entity cannot be |
| overridden by another module. |
| </p> |
| </dd> |
| </dl> |
| |
| <p>All visibilities are supported on many, but not all, ELF targets |
| (supported when the assembler supports the ‘<samp>.visibility</samp>’ |
| pseudo-op). Default visibility is supported everywhere. Hidden |
| visibility is supported on Darwin targets. |
| </p> |
| <p>The visibility attribute should be applied only to declarations that |
| would otherwise have external linkage. The attribute should be applied |
| consistently, so that the same entity should not be declared with |
| different settings of the attribute. |
| </p> |
| <p>In C++, the visibility attribute applies to types as well as functions |
| and objects, because in C++ types have linkage. A class must not have |
| greater visibility than its non-static data member types and bases, |
| and class members default to the visibility of their class. Also, a |
| declaration without explicit visibility is limited to the visibility |
| of its type. |
| </p> |
| <p>In C++, you can mark member functions and static member variables of a |
| class with the visibility attribute. This is useful if you know a |
| particular method or static member variable should only be used from |
| one shared object; then you can mark it hidden while the rest of the |
| class has default visibility. Care must be taken to avoid breaking |
| the One Definition Rule; for example, it is usually not useful to mark |
| an inline method as hidden without marking the whole class as hidden. |
| </p> |
| <p>A C++ namespace declaration can also have the visibility attribute. |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample">namespace nspace1 __attribute__ ((visibility ("protected"))) |
| { /* <span class="roman">Do something.</span> */; } |
| </pre></div> |
| |
| <p>This attribute applies only to the particular namespace body, not to |
| other definitions of the same namespace; it is equivalent to using |
| ‘<samp>#pragma GCC visibility</samp>’ before and after the namespace |
| definition (see <a href="Visibility-Pragmas.html#Visibility-Pragmas">Visibility Pragmas</a>). |
| </p> |
| <p>In C++, if a template argument has limited visibility, this |
| restriction is implicitly propagated to the template instantiation. |
| Otherwise, template instantiations and specializations default to the |
| visibility of their template. |
| </p> |
| <p>If both the template and enclosing class have explicit visibility, the |
| visibility from the template is used. |
| </p> |
| </dd> |
| <dt><code>vliw</code></dt> |
| <dd><a name="index-vliw-function-attribute_002c-MeP"></a> |
| <p>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. |
| </p> |
| </dd> |
| <dt><code>warn_unused_result</code></dt> |
| <dd><a name="index-warn_005funused_005fresult-function-attribute"></a> |
| <p>The <code>warn_unused_result</code> attribute causes a warning to be emitted |
| if a caller of the function with this attribute does not use its |
| return value. This is useful for functions where not checking |
| the result is either a security problem or always a bug, such as |
| <code>realloc</code>. |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample">int fn () __attribute__ ((warn_unused_result)); |
| int foo () |
| { |
| if (fn () < 0) return -1; |
| fn (); |
| return 0; |
| } |
| </pre></div> |
| |
| <p>results in warning on line 5. |
| </p> |
| </dd> |
| <dt><code>weak</code></dt> |
| <dd><a name="index-weak-function-attribute"></a> |
| <p>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. |
| </p> |
| </dd> |
| <dt><code>weakref</code></dt> |
| <dt><code>weakref ("<var>target</var>")</code></dt> |
| <dd><a name="index-weakref-function-attribute"></a> |
| <p>The <code>weakref</code> attribute marks a declaration as a weak reference. |
| Without arguments, it should be accompanied by an <code>alias</code> attribute |
| naming the target symbol. 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>. |
| </p> |
| <div class="smallexample"> |
| <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></div> |
| |
| <p>A weak reference is an alias that does not by itself require a |
| definition to be given for the target symbol. If the target symbol is |
| only referenced through weak references, then it becomes a <code>weak</code> |
| undefined symbol. If it is directly referenced, however, then such |
| strong references prevail, and a definition is required for the |
| symbol, not necessarily in the same translation unit. |
| </p> |
| <p>The effect is equivalent to moving all references to the alias to a |
| separate translation unit, renaming the alias to the aliased symbol, |
| declaring it as weak, compiling the two separate translation units and |
| performing a reloadable link on them. |
| </p> |
| <p>At present, a declaration to which <code>weakref</code> is attached can |
| only be <code>static</code>. |
| </p> |
| </dd> |
| </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-_0023pragma_002c-reason-for-not-using"></a> |
| <a name="index-pragma_002c-reason-for-not-using"></a> |
| <p>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. |
| </p> |
| <ol> |
| <li> It is impossible to generate <code>#pragma</code> commands from a macro. |
| |
| </li><li> There is no telling what the same <code>#pragma</code> might mean in another |
| compiler. |
| </li></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> |
| <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>. |
| </p> |
| <hr> |
| <div class="header"> |
| <p> |
| Next: <a href="Label-Attributes.html#Label-Attributes" accesskey="n" rel="next">Label Attributes</a>, Previous: <a href="Mixed-Declarations.html#Mixed-Declarations" accesskey="p" rel="prev">Mixed Declarations</a>, Up: <a href="C-Extensions.html#C-Extensions" accesskey="u" rel="up">C Extensions</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Option-Index.html#Option-Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| |
| |
| |
| </body> |
| </html> |