1<html lang="en"> 2<head> 3<title>Function Attributes - Using the GNU Compiler Collection (GCC)</title> 4<meta http-equiv="Content-Type" content="text/html"> 5<meta name="description" content="Using the GNU Compiler Collection (GCC)"> 6<meta name="generator" content="makeinfo 4.13"> 7<link title="Top" rel="start" href="index.html#Top"> 8<link rel="up" href="C-Extensions.html#C-Extensions" title="C Extensions"> 9<link rel="prev" href="Mixed-Declarations.html#Mixed-Declarations" title="Mixed Declarations"> 10<link rel="next" href="Attribute-Syntax.html#Attribute-Syntax" title="Attribute Syntax"> 11<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> 12<!-- 13Copyright (C) 1988-2013 Free Software Foundation, Inc. 14 15Permission is granted to copy, distribute and/or modify this document 16under the terms of the GNU Free Documentation License, Version 1.3 or 17any later version published by the Free Software Foundation; with the 18Invariant Sections being ``Funding Free Software'', the Front-Cover 19Texts being (a) (see below), and with the Back-Cover Texts being (b) 20(see below). A copy of the license is included in the section entitled 21``GNU Free Documentation License''. 22 23(a) The FSF's Front-Cover Text is: 24 25 A GNU Manual 26 27(b) The FSF's Back-Cover Text is: 28 29 You have freedom to copy and modify this GNU Manual, like GNU 30 software. Copies published by the Free Software Foundation raise 31 funds for GNU development.--> 32<meta http-equiv="Content-Style-Type" content="text/css"> 33<style type="text/css"><!-- 34 pre.display { font-family:inherit } 35 pre.format { font-family:inherit } 36 pre.smalldisplay { font-family:inherit; font-size:smaller } 37 pre.smallformat { font-family:inherit; font-size:smaller } 38 pre.smallexample { font-size:smaller } 39 pre.smalllisp { font-size:smaller } 40 span.sc { font-variant:small-caps } 41 span.roman { font-family:serif; font-weight:normal; } 42 span.sansserif { font-family:sans-serif; font-weight:normal; } 43--></style> 44<link rel="stylesheet" type="text/css" href="../cs.css"> 45</head> 46<body> 47<div class="node"> 48<a name="Function-Attributes"></a> 49<p> 50Next: <a rel="next" accesskey="n" href="Attribute-Syntax.html#Attribute-Syntax">Attribute Syntax</a>, 51Previous: <a rel="previous" accesskey="p" href="Mixed-Declarations.html#Mixed-Declarations">Mixed Declarations</a>, 52Up: <a rel="up" accesskey="u" href="C-Extensions.html#C-Extensions">C Extensions</a> 53<hr> 54</div> 55 56<h3 class="section">6.30 Declaring Attributes of Functions</h3> 57 58<p><a name="index-function-attributes-2580"></a><a name="index-declaring-attributes-of-functions-2581"></a><a name="index-functions-that-never-return-2582"></a><a name="index-functions-that-return-more-than-once-2583"></a><a name="index-functions-that-have-no-side-effects-2584"></a><a name="index-functions-in-arbitrary-sections-2585"></a><a name="index-functions-that-behave-like-malloc-2586"></a><a name="index-g_t_0040code_007bvolatile_007d-applied-to-function-2587"></a><a name="index-g_t_0040code_007bconst_007d-applied-to-function-2588"></a><a name="index-functions-with-_0040code_007bprintf_007d_002c-_0040code_007bscanf_007d_002c-_0040code_007bstrftime_007d-or-_0040code_007bstrfmon_007d-style-arguments-2589"></a><a name="index-functions-with-non_002dnull-pointer-arguments-2590"></a><a name="index-functions-that-are-passed-arguments-in-registers-on-the-386-2591"></a><a name="index-functions-that-pop-the-argument-stack-on-the-386-2592"></a><a name="index-functions-that-do-not-pop-the-argument-stack-on-the-386-2593"></a><a name="index-functions-that-have-different-compilation-options-on-the-386-2594"></a><a name="index-functions-that-have-different-optimization-options-2595"></a><a name="index-functions-that-are-dynamically-resolved-2596"></a> 59In GNU C, you declare certain things about functions called in your program 60which help the compiler optimize function calls and check your code more 61carefully. 62 63 <p>The keyword <code>__attribute__</code> allows you to specify special 64attributes when making a declaration. This keyword is followed by an 65attribute specification inside double parentheses. The following 66attributes are currently defined for functions on all targets: 67<code>aligned</code>, <code>alloc_size</code>, <code>noreturn</code>, 68<code>returns_twice</code>, <code>noinline</code>, <code>noclone</code>, 69<code>always_inline</code>, <code>flatten</code>, <code>pure</code>, <code>const</code>, 70<code>nothrow</code>, <code>sentinel</code>, <code>format</code>, <code>format_arg</code>, 71<code>no_instrument_function</code>, <code>no_split_stack</code>, 72<code>section</code>, <code>constructor</code>, 73<code>destructor</code>, <code>used</code>, <code>unused</code>, <code>deprecated</code>, 74<code>weak</code>, <code>malloc</code>, <code>alias</code>, <code>ifunc</code>, 75<code>warn_unused_result</code>, <code>nonnull</code>, <code>gnu_inline</code>, 76<code>externally_visible</code>, <code>hot</code>, <code>cold</code>, <code>artificial</code>, 77<code>no_sanitize_address</code>, <code>no_address_safety_analysis</code>, 78<code>error</code> and <code>warning</code>. 79Several other attributes are defined for functions on particular 80target systems. Other attributes, including <code>section</code> are 81supported for variables declarations (see <a href="Variable-Attributes.html#Variable-Attributes">Variable Attributes</a>) 82and for types (see <a href="Type-Attributes.html#Type-Attributes">Type Attributes</a>). 83 84 <p>GCC plugins may provide their own attributes. 85 86 <p>You may also specify attributes with ‘<samp><span class="samp">__</span></samp>’ preceding and following 87each keyword. This allows you to use them in header files without 88being concerned about a possible macro of the same name. For example, 89you may use <code>__noreturn__</code> instead of <code>noreturn</code>. 90 91 <p>See <a href="Attribute-Syntax.html#Attribute-Syntax">Attribute Syntax</a>, for details of the exact syntax for using 92attributes. 93 94 <dl> 95<!-- Keep this table alphabetized by attribute name. Treat _ as space. --> 96 97 <dt><code>alias ("</code><var>target</var><code>")</code><dd><a name="index-g_t_0040code_007balias_007d-attribute-2597"></a>The <code>alias</code> attribute causes the declaration to be emitted as an 98alias for another symbol, which must be specified. For instance, 99 100 <pre class="smallexample"> void __f () { /* <span class="roman">Do something.</span> */; } 101 void f () __attribute__ ((weak, alias ("__f"))); 102</pre> 103 <p class="noindent">defines ‘<samp><span class="samp">f</span></samp>’ to be a weak alias for ‘<samp><span class="samp">__f</span></samp>’. In C++, the 104mangled name for the target must be used. It is an error if ‘<samp><span class="samp">__f</span></samp>’ 105is not defined in the same translation unit. 106 107 <p>Not all target machines support this attribute. 108 109 <br><dt><code>aligned (</code><var>alignment</var><code>)</code><dd><a name="index-g_t_0040code_007baligned_007d-attribute-2598"></a>This attribute specifies a minimum alignment for the function, 110measured in bytes. 111 112 <p>You cannot use this attribute to decrease the alignment of a function, 113only to increase it. However, when you explicitly specify a function 114alignment this overrides the effect of the 115<samp><span class="option">-falign-functions</span></samp> (see <a href="Optimize-Options.html#Optimize-Options">Optimize Options</a>) option for this 116function. 117 118 <p>Note that the effectiveness of <code>aligned</code> attributes may be 119limited by inherent limitations in your linker. On many systems, the 120linker is only able to arrange for functions to be aligned up to a 121certain maximum alignment. (For some linkers, the maximum supported 122alignment may be very very small.) See your linker documentation for 123further information. 124 125 <p>The <code>aligned</code> attribute can also be used for variables and fields 126(see <a href="Variable-Attributes.html#Variable-Attributes">Variable Attributes</a>.) 127 128 <br><dt><code>alloc_size</code><dd><a name="index-g_t_0040code_007balloc_005fsize_007d-attribute-2599"></a>The <code>alloc_size</code> attribute is used to tell the compiler that the 129function return value points to memory, where the size is given by 130one or two of the functions parameters. GCC uses this 131information to improve the correctness of <code>__builtin_object_size</code>. 132 133 <p>The function parameter(s) denoting the allocated size are specified by 134one or two integer arguments supplied to the attribute. The allocated size 135is either the value of the single function argument specified or the product 136of the two function arguments specified. Argument numbering starts at 137one. 138 139 <p>For instance, 140 141 <pre class="smallexample"> void* my_calloc(size_t, size_t) __attribute__((alloc_size(1,2))) 142 void my_realloc(void*, size_t) __attribute__((alloc_size(2))) 143</pre> 144 <p class="noindent">declares that <code>my_calloc</code> returns memory of the size given by 145the product of parameter 1 and 2 and that <code>my_realloc</code> returns memory 146of the size given by parameter 2. 147 148 <br><dt><code>always_inline</code><dd><a name="index-g_t_0040code_007balways_005finline_007d-function-attribute-2600"></a>Generally, functions are not inlined unless optimization is specified. 149For functions declared inline, this attribute inlines the function even 150if no optimization level is specified. 151 152 <br><dt><code>gnu_inline</code><dd><a name="index-g_t_0040code_007bgnu_005finline_007d-function-attribute-2601"></a>This attribute should be used with a function that is also declared 153with the <code>inline</code> keyword. It directs GCC to treat the function 154as if it were defined in gnu90 mode even when compiling in C99 or 155gnu99 mode. 156 157 <p>If the function is declared <code>extern</code>, then this definition of the 158function is used only for inlining. In no case is the function 159compiled as a standalone function, not even if you take its address 160explicitly. Such an address becomes an external reference, as if you 161had only declared the function, and had not defined it. This has 162almost the effect of a macro. The way to use this is to put a 163function definition in a header file with this attribute, and put 164another copy of the function, without <code>extern</code>, in a library 165file. The definition in the header file causes most calls to the 166function to be inlined. If any uses of the function remain, they 167refer to the single copy in the library. Note that the two 168definitions of the functions need not be precisely the same, although 169if they do not have the same effect your program may behave oddly. 170 171 <p>In C, if the function is neither <code>extern</code> nor <code>static</code>, then 172the function is compiled as a standalone function, as well as being 173inlined where possible. 174 175 <p>This is how GCC traditionally handled functions declared 176<code>inline</code>. Since ISO C99 specifies a different semantics for 177<code>inline</code>, this function attribute is provided as a transition 178measure and as a useful feature in its own right. This attribute is 179available in GCC 4.1.3 and later. It is available if either of the 180preprocessor macros <code>__GNUC_GNU_INLINE__</code> or 181<code>__GNUC_STDC_INLINE__</code> are defined. See <a href="Inline.html#Inline">An Inline Function is As Fast As a Macro</a>. 182 183 <p>In C++, this attribute does not depend on <code>extern</code> in any way, 184but it still requires the <code>inline</code> keyword to enable its special 185behavior. 186 187 <br><dt><code>artificial</code><dd><a name="index-g_t_0040code_007bartificial_007d-function-attribute-2602"></a>This attribute is useful for small inline wrappers that if possible 188should appear during debugging as a unit. Depending on the debug 189info format it either means marking the function as artificial 190or using the caller location for all instructions within the inlined 191body. 192 193 <br><dt><code>bank_switch</code><dd><a name="index-interrupt-handler-functions-2603"></a>When added to an interrupt handler with the M32C port, causes the 194prologue and epilogue to use bank switching to preserve the registers 195rather than saving them on the stack. 196 197 <br><dt><code>flatten</code><dd><a name="index-g_t_0040code_007bflatten_007d-function-attribute-2604"></a>Generally, inlining into a function is limited. For a function marked with 198this attribute, every call inside this function is inlined, if possible. 199Whether the function itself is considered for inlining depends on its size and 200the current inlining parameters. 201 202 <br><dt><code>error ("</code><var>message</var><code>")</code><dd><a name="index-g_t_0040code_007berror_007d-function-attribute-2605"></a>If this attribute is used on a function declaration and a call to such a function 203is not eliminated through dead code elimination or other optimizations, an error 204that includes <var>message</var> is diagnosed. This is useful 205for compile-time checking, especially together with <code>__builtin_constant_p</code> 206and inline functions where checking the inline function arguments is not 207possible through <code>extern char [(condition) ? 1 : -1];</code> tricks. 208While it is possible to leave the function undefined and thus invoke 209a link failure, when using this attribute the problem is diagnosed 210earlier and with exact location of the call even in presence of inline 211functions or when not emitting debugging information. 212 213 <br><dt><code>warning ("</code><var>message</var><code>")</code><dd><a name="index-g_t_0040code_007bwarning_007d-function-attribute-2606"></a>If this attribute is used on a function declaration and a call to such a function 214is not eliminated through dead code elimination or other optimizations, a warning 215that includes <var>message</var> is diagnosed. This is useful 216for compile-time checking, especially together with <code>__builtin_constant_p</code> 217and inline functions. While it is possible to define the function with 218a message in <code>.gnu.warning*</code> section, when using this attribute the problem 219is diagnosed earlier and with exact location of the call even in presence 220of inline functions or when not emitting debugging information. 221 222 <br><dt><code>cdecl</code><dd><a name="index-functions-that-do-pop-the-argument-stack-on-the-386-2607"></a><a name="index-mrtd-2608"></a>On the Intel 386, the <code>cdecl</code> attribute causes the compiler to 223assume that the calling function pops off the stack space used to 224pass arguments. This is 225useful to override the effects of the <samp><span class="option">-mrtd</span></samp> switch. 226 227 <br><dt><code>const</code><dd><a name="index-g_t_0040code_007bconst_007d-function-attribute-2609"></a>Many functions do not examine any values except their arguments, and 228have no effects except the return value. Basically this is just slightly 229more strict class than the <code>pure</code> attribute below, since function is not 230allowed to read global memory. 231 232 <p><a name="index-pointer-arguments-2610"></a>Note that a function that has pointer arguments and examines the data 233pointed to must <em>not</em> be declared <code>const</code>. Likewise, a 234function that calls a non-<code>const</code> function usually must not be 235<code>const</code>. It does not make sense for a <code>const</code> function to 236return <code>void</code>. 237 238 <p>The attribute <code>const</code> is not implemented in GCC versions earlier 239than 2.5. An alternative way to declare that a function has no side 240effects, which works in the current version and in some older versions, 241is as follows: 242 243 <pre class="smallexample"> typedef int intfn (); 244 245 extern const intfn square; 246</pre> 247 <p class="noindent">This approach does not work in GNU C++ from 2.6.0 on, since the language 248specifies that the ‘<samp><span class="samp">const</span></samp>’ must be attached to the return value. 249 250 <br><dt><code>constructor</code><dt><code>destructor</code><dt><code>constructor (</code><var>priority</var><code>)</code><dt><code>destructor (</code><var>priority</var><code>)</code><dd><a name="index-g_t_0040code_007bconstructor_007d-function-attribute-2611"></a><a name="index-g_t_0040code_007bdestructor_007d-function-attribute-2612"></a>The <code>constructor</code> attribute causes the function to be called 251automatically before execution enters <code>main ()</code>. Similarly, the 252<code>destructor</code> attribute causes the function to be called 253automatically after <code>main ()</code> completes or <code>exit ()</code> is 254called. Functions with these attributes are useful for 255initializing data that is used implicitly during the execution of 256the program. 257 258 <p>You may provide an optional integer priority to control the order in 259which constructor and destructor functions are run. A constructor 260with a smaller priority number runs before a constructor with a larger 261priority number; the opposite relationship holds for destructors. So, 262if you have a constructor that allocates a resource and a destructor 263that deallocates the same resource, both functions typically have the 264same priority. The priorities for constructor and destructor 265functions are the same as those specified for namespace-scope C++ 266objects (see <a href="C_002b_002b-Attributes.html#C_002b_002b-Attributes">C++ Attributes</a>). 267 268 <p>These attributes are not currently implemented for Objective-C. 269 270 <br><dt><code>deprecated</code><dt><code>deprecated (</code><var>msg</var><code>)</code><dd><a name="index-g_t_0040code_007bdeprecated_007d-attribute_002e-2613"></a>The <code>deprecated</code> attribute results in a warning if the function 271is used anywhere in the source file. This is useful when identifying 272functions that are expected to be removed in a future version of a 273program. The warning also includes the location of the declaration 274of the deprecated function, to enable users to easily find further 275information about why the function is deprecated, or what they should 276do instead. Note that the warnings only occurs for uses: 277 278 <pre class="smallexample"> int old_fn () __attribute__ ((deprecated)); 279 int old_fn (); 280 int (*fn_ptr)() = old_fn; 281</pre> 282 <p class="noindent">results in a warning on line 3 but not line 2. The optional <var>msg</var> 283argument, which must be a string, is printed in the warning if 284present. 285 286 <p>The <code>deprecated</code> attribute can also be used for variables and 287types (see <a href="Variable-Attributes.html#Variable-Attributes">Variable Attributes</a>, see <a href="Type-Attributes.html#Type-Attributes">Type Attributes</a>.) 288 289 <br><dt><code>disinterrupt</code><dd><a name="index-g_t_0040code_007bdisinterrupt_007d-attribute-2614"></a>On Epiphany and MeP targets, this attribute causes the compiler to emit 290instructions to disable interrupts for the duration of the given 291function. 292 293 <br><dt><code>dllexport</code><dd><a name="index-g_t_0040code_007b_005f_005fdeclspec_0028dllexport_0029_007d-2615"></a>On Microsoft Windows targets and Symbian OS targets the 294<code>dllexport</code> attribute causes the compiler to provide a global 295pointer to a pointer in a DLL, so that it can be referenced with the 296<code>dllimport</code> attribute. On Microsoft Windows targets, the pointer 297name is formed by combining <code>_imp__</code> and the function or variable 298name. 299 300 <p>You can use <code>__declspec(dllexport)</code> as a synonym for 301<code>__attribute__ ((dllexport))</code> for compatibility with other 302compilers. 303 304 <p>On systems that support the <code>visibility</code> attribute, this 305attribute also implies “default” visibility. It is an error to 306explicitly specify any other visibility. 307 308 <p>In previous versions of GCC, the <code>dllexport</code> attribute was ignored 309for inlined functions, unless the <samp><span class="option">-fkeep-inline-functions</span></samp> flag 310had been used. The default behavior now is to emit all dllexported 311inline functions; however, this can cause object file-size bloat, in 312which case the old behavior can be restored by using 313<samp><span class="option">-fno-keep-inline-dllexport</span></samp>. 314 315 <p>The attribute is also ignored for undefined symbols. 316 317 <p>When applied to C++ classes, the attribute marks defined non-inlined 318member functions and static data members as exports. Static consts 319initialized in-class are not marked unless they are also defined 320out-of-class. 321 322 <p>For Microsoft Windows targets there are alternative methods for 323including the symbol in the DLL's export table such as using a 324<samp><span class="file">.def</span></samp> file with an <code>EXPORTS</code> section or, with GNU ld, using 325the <samp><span class="option">--export-all</span></samp> linker flag. 326 327 <br><dt><code>dllimport</code><dd><a name="index-g_t_0040code_007b_005f_005fdeclspec_0028dllimport_0029_007d-2616"></a>On Microsoft Windows and Symbian OS targets, the <code>dllimport</code> 328attribute causes the compiler to reference a function or variable via 329a global pointer to a pointer that is set up by the DLL exporting the 330symbol. The attribute implies <code>extern</code>. On Microsoft Windows 331targets, the pointer name is formed by combining <code>_imp__</code> and the 332function or variable name. 333 334 <p>You can use <code>__declspec(dllimport)</code> as a synonym for 335<code>__attribute__ ((dllimport))</code> for compatibility with other 336compilers. 337 338 <p>On systems that support the <code>visibility</code> attribute, this 339attribute also implies “default” visibility. It is an error to 340explicitly specify any other visibility. 341 342 <p>Currently, the attribute is ignored for inlined functions. If the 343attribute is applied to a symbol <em>definition</em>, an error is reported. 344If a symbol previously declared <code>dllimport</code> is later defined, the 345attribute is ignored in subsequent references, and a warning is emitted. 346The attribute is also overridden by a subsequent declaration as 347<code>dllexport</code>. 348 349 <p>When applied to C++ classes, the attribute marks non-inlined 350member functions and static data members as imports. However, the 351attribute is ignored for virtual methods to allow creation of vtables 352using thunks. 353 354 <p>On the SH Symbian OS target the <code>dllimport</code> attribute also has 355another affect—it can cause the vtable and run-time type information 356for a class to be exported. This happens when the class has a 357dllimported constructor or a non-inline, non-pure virtual function 358and, for either of those two conditions, the class also has an inline 359constructor or destructor and has a key function that is defined in 360the current translation unit. 361 362 <p>For Microsoft Windows targets the use of the <code>dllimport</code> 363attribute on functions is not necessary, but provides a small 364performance benefit by eliminating a thunk in the DLL. The use of the 365<code>dllimport</code> attribute on imported variables was required on older 366versions of the GNU linker, but can now be avoided by passing the 367<samp><span class="option">--enable-auto-import</span></samp> switch to the GNU linker. As with 368functions, using the attribute for a variable eliminates a thunk in 369the DLL. 370 371 <p>One drawback to using this attribute is that a pointer to a 372<em>variable</em> marked as <code>dllimport</code> cannot be used as a constant 373address. However, a pointer to a <em>function</em> with the 374<code>dllimport</code> attribute can be used as a constant initializer; in 375this case, the address of a stub function in the import lib is 376referenced. On Microsoft Windows targets, the attribute can be disabled 377for functions by setting the <samp><span class="option">-mnop-fun-dllimport</span></samp> flag. 378 379 <br><dt><code>eightbit_data</code><dd><a name="index-eight_002dbit-data-on-the-H8_002f300_002c-H8_002f300H_002c-and-H8S-2617"></a>Use this attribute on the H8/300, H8/300H, and H8S to indicate that the specified 380variable should be placed into the eight-bit data section. 381The compiler generates more efficient code for certain operations 382on data in the eight-bit data area. Note the eight-bit data area is limited to 383256 bytes of data. 384 385 <p>You must use GAS and GLD from GNU binutils version 2.7 or later for 386this attribute to work correctly. 387 388 <br><dt><code>exception_handler</code><dd><a name="index-exception-handler-functions-on-the-Blackfin-processor-2618"></a>Use this attribute on the Blackfin to indicate that the specified function 389is an exception handler. The compiler generates function entry and 390exit sequences suitable for use in an exception handler when this 391attribute is present. 392 393 <br><dt><code>externally_visible</code><dd><a name="index-g_t_0040code_007bexternally_005fvisible_007d-attribute_002e-2619"></a>This attribute, attached to a global variable or function, nullifies 394the effect of the <samp><span class="option">-fwhole-program</span></samp> command-line option, so the 395object remains visible outside the current compilation unit. 396 397 <p>If <samp><span class="option">-fwhole-program</span></samp> is used together with <samp><span class="option">-flto</span></samp> and 398<samp><span class="command">gold</span></samp> is used as the linker plugin, 399<code>externally_visible</code> attributes are automatically added to functions 400(not variable yet due to a current <samp><span class="command">gold</span></samp> issue) 401that are accessed outside of LTO objects according to resolution file 402produced by <samp><span class="command">gold</span></samp>. 403For other linkers that cannot generate resolution file, 404explicit <code>externally_visible</code> attributes are still necessary. 405 406 <br><dt><code>far</code><dd><a name="index-functions-that-handle-memory-bank-switching-2620"></a>On 68HC11 and 68HC12 the <code>far</code> attribute causes the compiler to 407use a calling convention that takes care of switching memory banks when 408entering and leaving a function. This calling convention is also the 409default when using the <samp><span class="option">-mlong-calls</span></samp> option. 410 411 <p>On 68HC12 the compiler uses the <code>call</code> and <code>rtc</code> instructions 412to call and return from a function. 413 414 <p>On 68HC11 the compiler generates a sequence of instructions 415to invoke a board-specific routine to switch the memory bank and call the 416real function. The board-specific routine simulates a <code>call</code>. 417At the end of a function, it jumps to a board-specific routine 418instead of using <code>rts</code>. The board-specific return routine simulates 419the <code>rtc</code>. 420 421 <p>On MeP targets this causes the compiler to use a calling convention 422that assumes the called function is too far away for the built-in 423addressing modes. 424 425 <br><dt><code>fast_interrupt</code><dd><a name="index-interrupt-handler-functions-2621"></a>Use this attribute on the M32C and RX ports to indicate that the specified 426function is a fast interrupt handler. This is just like the 427<code>interrupt</code> attribute, except that <code>freit</code> is used to return 428instead of <code>reit</code>. 429 430 <br><dt><code>fastcall</code><dd><a name="index-functions-that-pop-the-argument-stack-on-the-386-2622"></a>On the Intel 386, the <code>fastcall</code> attribute causes the compiler to 431pass the first argument (if of integral type) in the register ECX and 432the second argument (if of integral type) in the register EDX. Subsequent 433and other typed arguments are passed on the stack. The called function 434pops the arguments off the stack. If the number of arguments is variable all 435arguments are pushed on the stack. 436 437 <br><dt><code>thiscall</code><dd><a name="index-functions-that-pop-the-argument-stack-on-the-386-2623"></a>On the Intel 386, the <code>thiscall</code> attribute causes the compiler to 438pass the first argument (if of integral type) in the register ECX. 439Subsequent and other typed arguments are passed on the stack. The called 440function pops the arguments off the stack. 441If the number of arguments is variable all arguments are pushed on the 442stack. 443The <code>thiscall</code> attribute is intended for C++ non-static member functions. 444As a GCC extension, this calling convention can be used for C functions 445and for static member methods. 446 447 <br><dt><code>format (</code><var>archetype</var><code>, </code><var>string-index</var><code>, </code><var>first-to-check</var><code>)</code><dd><a name="index-g_t_0040code_007bformat_007d-function-attribute-2624"></a><a name="index-Wformat-2625"></a>The <code>format</code> attribute specifies that a function takes <code>printf</code>, 448<code>scanf</code>, <code>strftime</code> or <code>strfmon</code> style arguments that 449should be type-checked against a format string. For example, the 450declaration: 451 452 <pre class="smallexample"> extern int 453 my_printf (void *my_object, const char *my_format, ...) 454 __attribute__ ((format (printf, 2, 3))); 455</pre> 456 <p class="noindent">causes the compiler to check the arguments in calls to <code>my_printf</code> 457for consistency with the <code>printf</code> style format string argument 458<code>my_format</code>. 459 460 <p>The parameter <var>archetype</var> determines how the format string is 461interpreted, and should be <code>printf</code>, <code>scanf</code>, <code>strftime</code>, 462<code>gnu_printf</code>, <code>gnu_scanf</code>, <code>gnu_strftime</code> or 463<code>strfmon</code>. (You can also use <code>__printf__</code>, 464<code>__scanf__</code>, <code>__strftime__</code> or <code>__strfmon__</code>.) On 465MinGW targets, <code>ms_printf</code>, <code>ms_scanf</code>, and 466<code>ms_strftime</code> are also present. 467<var>archetype</var> values such as <code>printf</code> refer to the formats accepted 468by the system's C runtime library, 469while values prefixed with ‘<samp><span class="samp">gnu_</span></samp>’ always refer 470to the formats accepted by the GNU C Library. On Microsoft Windows 471targets, values prefixed with ‘<samp><span class="samp">ms_</span></samp>’ refer to the formats accepted by the 472<samp><span class="file">msvcrt.dll</span></samp> library. 473The parameter <var>string-index</var> 474specifies which argument is the format string argument (starting 475from 1), while <var>first-to-check</var> is the number of the first 476argument to check against the format string. For functions 477where the arguments are not available to be checked (such as 478<code>vprintf</code>), specify the third parameter as zero. In this case the 479compiler only checks the format string for consistency. For 480<code>strftime</code> formats, the third parameter is required to be zero. 481Since non-static C++ methods have an implicit <code>this</code> argument, the 482arguments of such methods should be counted from two, not one, when 483giving values for <var>string-index</var> and <var>first-to-check</var>. 484 485 <p>In the example above, the format string (<code>my_format</code>) is the second 486argument of the function <code>my_print</code>, and the arguments to check 487start with the third argument, so the correct parameters for the format 488attribute are 2 and 3. 489 490 <p><a name="index-ffreestanding-2626"></a><a name="index-fno_002dbuiltin-2627"></a>The <code>format</code> attribute allows you to identify your own functions 491that take format strings as arguments, so that GCC can check the 492calls to these functions for errors. The compiler always (unless 493<samp><span class="option">-ffreestanding</span></samp> or <samp><span class="option">-fno-builtin</span></samp> is used) checks formats 494for the standard library functions <code>printf</code>, <code>fprintf</code>, 495<code>sprintf</code>, <code>scanf</code>, <code>fscanf</code>, <code>sscanf</code>, <code>strftime</code>, 496<code>vprintf</code>, <code>vfprintf</code> and <code>vsprintf</code> whenever such 497warnings are requested (using <samp><span class="option">-Wformat</span></samp>), so there is no need to 498modify the header file <samp><span class="file">stdio.h</span></samp>. In C99 mode, the functions 499<code>snprintf</code>, <code>vsnprintf</code>, <code>vscanf</code>, <code>vfscanf</code> and 500<code>vsscanf</code> are also checked. Except in strictly conforming C 501standard modes, the X/Open function <code>strfmon</code> is also checked as 502are <code>printf_unlocked</code> and <code>fprintf_unlocked</code>. 503See <a href="C-Dialect-Options.html#C-Dialect-Options">Options Controlling C Dialect</a>. 504 505 <p>For Objective-C dialects, <code>NSString</code> (or <code>__NSString__</code>) is 506recognized in the same context. Declarations including these format attributes 507are parsed for correct syntax, however the result of checking of such format 508strings is not yet defined, and is not carried out by this version of the 509compiler. 510 511 <p>The target may also provide additional types of format checks. 512See <a href="Target-Format-Checks.html#Target-Format-Checks">Format Checks Specific to Particular Target Machines</a>. 513 514 <br><dt><code>format_arg (</code><var>string-index</var><code>)</code><dd><a name="index-g_t_0040code_007bformat_005farg_007d-function-attribute-2628"></a><a name="index-Wformat_002dnonliteral-2629"></a>The <code>format_arg</code> attribute specifies that a function takes a format 515string for a <code>printf</code>, <code>scanf</code>, <code>strftime</code> or 516<code>strfmon</code> style function and modifies it (for example, to translate 517it into another language), so the result can be passed to a 518<code>printf</code>, <code>scanf</code>, <code>strftime</code> or <code>strfmon</code> style 519function (with the remaining arguments to the format function the same 520as they would have been for the unmodified string). For example, the 521declaration: 522 523 <pre class="smallexample"> extern char * 524 my_dgettext (char *my_domain, const char *my_format) 525 __attribute__ ((format_arg (2))); 526</pre> 527 <p class="noindent">causes the compiler to check the arguments in calls to a <code>printf</code>, 528<code>scanf</code>, <code>strftime</code> or <code>strfmon</code> type function, whose 529format string argument is a call to the <code>my_dgettext</code> function, for 530consistency with the format string argument <code>my_format</code>. If the 531<code>format_arg</code> attribute had not been specified, all the compiler 532could tell in such calls to format functions would be that the format 533string argument is not constant; this would generate a warning when 534<samp><span class="option">-Wformat-nonliteral</span></samp> is used, but the calls could not be checked 535without the attribute. 536 537 <p>The parameter <var>string-index</var> specifies which argument is the format 538string argument (starting from one). Since non-static C++ methods have 539an implicit <code>this</code> argument, the arguments of such methods should 540be counted from two. 541 542 <p>The <code>format_arg</code> attribute allows you to identify your own 543functions that modify format strings, so that GCC can check the 544calls to <code>printf</code>, <code>scanf</code>, <code>strftime</code> or <code>strfmon</code> 545type function whose operands are a call to one of your own function. 546The compiler always treats <code>gettext</code>, <code>dgettext</code>, and 547<code>dcgettext</code> in this manner except when strict ISO C support is 548requested by <samp><span class="option">-ansi</span></samp> or an appropriate <samp><span class="option">-std</span></samp> option, or 549<samp><span class="option">-ffreestanding</span></samp> or <samp><span class="option">-fno-builtin</span></samp> 550is used. See <a href="C-Dialect-Options.html#C-Dialect-Options">Options Controlling C Dialect</a>. 551 552 <p>For Objective-C dialects, the <code>format-arg</code> attribute may refer to an 553<code>NSString</code> reference for compatibility with the <code>format</code> attribute 554above. 555 556 <p>The target may also allow additional types in <code>format-arg</code> attributes. 557See <a href="Target-Format-Checks.html#Target-Format-Checks">Format Checks Specific to Particular Target Machines</a>. 558 559 <br><dt><code>function_vector</code><dd><a name="index-calling-functions-through-the-function-vector-on-H8_002f300_002c-M16C_002c-M32C-and-SH2A-processors-2630"></a>Use this attribute on the H8/300, H8/300H, and H8S to indicate that the specified 560function should be called through the function vector. Calling a 561function through the function vector reduces code size, however; 562the function vector has a limited size (maximum 128 entries on the H8/300 563and 64 entries on the H8/300H and H8S) and shares space with the interrupt vector. 564 565 <p>On SH2A targets, this attribute declares a function to be called using the 566TBR relative addressing mode. The argument to this attribute is the entry 567number of the same function in a vector table containing all the TBR 568relative addressable functions. For correct operation the TBR must be setup 569accordingly to point to the start of the vector table before any functions with 570this attribute are invoked. Usually a good place to do the initialization is 571the startup routine. The TBR relative vector table can have at max 256 function 572entries. The jumps to these functions are generated using a SH2A specific, 573non delayed branch instruction JSR/N @(disp8,TBR). You must use GAS and GLD 574from GNU binutils version 2.7 or later for this attribute to work correctly. 575 576 <p>Please refer the example of M16C target, to see the use of this 577attribute while declaring a function, 578 579 <p>In an application, for a function being called once, this attribute 580saves at least 8 bytes of code; and if other successive calls are being 581made to the same function, it saves 2 bytes of code per each of these 582calls. 583 584 <p>On M16C/M32C targets, the <code>function_vector</code> attribute declares a 585special page subroutine call function. Use of this attribute reduces 586the code size by 2 bytes for each call generated to the 587subroutine. The argument to the attribute is the vector number entry 588from the special page vector table which contains the 16 low-order 589bits of the subroutine's entry address. Each vector table has special 590page number (18 to 255) that is used in <code>jsrs</code> instructions. 591Jump addresses of the routines are generated by adding 0x0F0000 (in 592case of M16C targets) or 0xFF0000 (in case of M32C targets), to the 5932-byte addresses set in the vector table. Therefore you need to ensure 594that all the special page vector routines should get mapped within the 595address range 0x0F0000 to 0x0FFFFF (for M16C) and 0xFF0000 to 0xFFFFFF 596(for M32C). 597 598 <p>In the following example 2 bytes are saved for each call to 599function <code>foo</code>. 600 601 <pre class="smallexample"> void foo (void) __attribute__((function_vector(0x18))); 602 void foo (void) 603 { 604 } 605 606 void bar (void) 607 { 608 foo(); 609 } 610</pre> 611 <p>If functions are defined in one file and are called in another file, 612then be sure to write this declaration in both files. 613 614 <p>This attribute is ignored for R8C target. 615 616 <br><dt><code>ifunc ("</code><var>resolver</var><code>")</code><dd><a name="index-g_t_0040code_007bifunc_007d-attribute-2631"></a>The <code>ifunc</code> attribute is used to mark a function as an indirect 617function using the STT_GNU_IFUNC symbol type extension to the ELF 618standard. This allows the resolution of the symbol value to be 619determined dynamically at load time, and an optimized version of the 620routine can be selected for the particular processor or other system 621characteristics determined then. To use this attribute, first define 622the implementation functions available, and a resolver function that 623returns a pointer to the selected implementation function. The 624implementation functions' declarations must match the API of the 625function being implemented, the resolver's declaration is be a 626function returning pointer to void function returning void: 627 628 <pre class="smallexample"> void *my_memcpy (void *dst, const void *src, size_t len) 629 { 630 ... 631 } 632 633 static void (*resolve_memcpy (void)) (void) 634 { 635 return my_memcpy; // we'll just always select this routine 636 } 637</pre> 638 <p class="noindent">The exported header file declaring the function the user calls would 639contain: 640 641 <pre class="smallexample"> extern void *memcpy (void *, const void *, size_t); 642</pre> 643 <p class="noindent">allowing the user to call this as a regular function, unaware of the 644implementation. Finally, the indirect function needs to be defined in 645the same translation unit as the resolver function: 646 647 <pre class="smallexample"> void *memcpy (void *, const void *, size_t) 648 __attribute__ ((ifunc ("resolve_memcpy"))); 649</pre> 650 <p>Indirect functions cannot be weak, and require a recent binutils (at 651least version 2.20.1), and GNU C library (at least version 2.11.1). 652 653 <br><dt><code>interrupt</code><dd><a name="index-interrupt-handler-functions-2632"></a>Use this attribute on the ARM, AVR, CR16, Epiphany, M32C, M32R/D, m68k, MeP, MIPS, 654RL78, RX and Xstormy16 ports to indicate that the specified function is an 655interrupt handler. The compiler generates function entry and exit 656sequences suitable for use in an interrupt handler when this attribute 657is present. With Epiphany targets it may also generate a special section with 658code to initialize the interrupt vector table. 659 660 <p>Note, interrupt handlers for the Blackfin, H8/300, H8/300H, H8S, MicroBlaze, 661and SH processors can be specified via the <code>interrupt_handler</code> attribute. 662 663 <p>Note, on the AVR, the hardware globally disables interrupts when an 664interrupt is executed. The first instruction of an interrupt handler 665declared with this attribute is a <code>SEI</code> instruction to 666re-enable interrupts. See also the <code>signal</code> function attribute 667that does not insert a <code>SEI</code> instruction. If both <code>signal</code> and 668<code>interrupt</code> are specified for the same function, <code>signal</code> 669is silently ignored. 670 671 <p>Note, for the ARM, you can specify the kind of interrupt to be handled by 672adding an optional parameter to the interrupt attribute like this: 673 674 <pre class="smallexample"> void f () __attribute__ ((interrupt ("IRQ"))); 675</pre> 676 <p class="noindent">Permissible values for this parameter are: <code>IRQ</code>, <code>FIQ</code>, 677<code>SWI</code>, <code>ABORT</code> and <code>UNDEF</code>. 678 679 <p>On ARMv7-M the interrupt type is ignored, and the attribute means the function 680may be called with a word-aligned stack pointer. 681 682 <p>On Epiphany targets one or more optional parameters can be added like this: 683 684 <pre class="smallexample"> void __attribute__ ((interrupt ("dma0, dma1"))) universal_dma_handler (); 685</pre> 686 <p>Permissible values for these parameters are: <code>reset</code><!-- /@w -->, 687<code>software_exception</code><!-- /@w -->, <code>page_miss</code><!-- /@w -->, 688<code>timer0</code><!-- /@w -->, <code>timer1</code><!-- /@w -->, <code>message</code><!-- /@w -->, 689<code>dma0</code><!-- /@w -->, <code>dma1</code><!-- /@w -->, <code>wand</code><!-- /@w --> and <code>swi</code><!-- /@w -->. 690Multiple parameters indicate that multiple entries in the interrupt 691vector table should be initialized for this function, i.e. for each 692parameter <var>name</var><!-- /@w -->, a jump to the function is emitted in 693the section ivt_entry_<var>name</var><!-- /@w -->. The parameter(s) may be omitted 694entirely, in which case no interrupt vector table entry is provided. 695 696 <p>Note, on Epiphany targets, interrupts are enabled inside the function 697unless the <code>disinterrupt</code> attribute is also specified. 698 699 <p>On Epiphany targets, you can also use the following attribute to 700modify the behavior of an interrupt handler: 701 <dl> 702<dt><code>forwarder_section</code><dd><a name="index-g_t_0040code_007bforwarder_005fsection_007d-attribute-2633"></a>The interrupt handler may be in external memory which cannot be 703reached by a branch instruction, so generate a local memory trampoline 704to transfer control. The single parameter identifies the section where 705the trampoline is placed. 706</dl> 707 708 <p>The following examples are all valid uses of these attributes on 709Epiphany targets: 710 <pre class="smallexample"> void __attribute__ ((interrupt)) universal_handler (); 711 void __attribute__ ((interrupt ("dma1"))) dma1_handler (); 712 void __attribute__ ((interrupt ("dma0, dma1"))) universal_dma_handler (); 713 void __attribute__ ((interrupt ("timer0"), disinterrupt)) 714 fast_timer_handler (); 715 void __attribute__ ((interrupt ("dma0, dma1"), forwarder_section ("tramp"))) 716 external_dma_handler (); 717</pre> 718 <p>On MIPS targets, you can use the following attributes to modify the behavior 719of an interrupt handler: 720 <dl> 721<dt><code>use_shadow_register_set</code><dd><a name="index-g_t_0040code_007buse_005fshadow_005fregister_005fset_007d-attribute-2634"></a>Assume that the handler uses a shadow register set, instead of 722the main general-purpose registers. 723 724 <br><dt><code>keep_interrupts_masked</code><dd><a name="index-g_t_0040code_007bkeep_005finterrupts_005fmasked_007d-attribute-2635"></a>Keep interrupts masked for the whole function. Without this attribute, 725GCC tries to reenable interrupts for as much of the function as it can. 726 727 <br><dt><code>use_debug_exception_return</code><dd><a name="index-g_t_0040code_007buse_005fdebug_005fexception_005freturn_007d-attribute-2636"></a>Return using the <code>deret</code> instruction. Interrupt handlers that don't 728have this attribute return using <code>eret</code> instead. 729</dl> 730 731 <p>You can use any combination of these attributes, as shown below: 732 <pre class="smallexample"> void __attribute__ ((interrupt)) v0 (); 733 void __attribute__ ((interrupt, use_shadow_register_set)) v1 (); 734 void __attribute__ ((interrupt, keep_interrupts_masked)) v2 (); 735 void __attribute__ ((interrupt, use_debug_exception_return)) v3 (); 736 void __attribute__ ((interrupt, use_shadow_register_set, 737 keep_interrupts_masked)) v4 (); 738 void __attribute__ ((interrupt, use_shadow_register_set, 739 use_debug_exception_return)) v5 (); 740 void __attribute__ ((interrupt, keep_interrupts_masked, 741 use_debug_exception_return)) v6 (); 742 void __attribute__ ((interrupt, use_shadow_register_set, 743 keep_interrupts_masked, 744 use_debug_exception_return)) v7 (); 745</pre> 746 <p>On RL78, use <code>brk_interrupt</code> instead of <code>interrupt</code> for 747handlers intended to be used with the <code>BRK</code> opcode (i.e. those 748that must end with <code>RETB</code> instead of <code>RETI</code>). 749 750 <br><dt><code>interrupt_handler</code><dd><a name="index-interrupt-handler-functions-on-the-Blackfin_002c-m68k_002c-H8_002f300-and-SH-processors-2637"></a>Use this attribute on the Blackfin, m68k, H8/300, H8/300H, H8S, and SH to 751indicate that the specified function is an interrupt handler. The compiler 752generates function entry and exit sequences suitable for use in an 753interrupt handler when this attribute is present. 754 755 <br><dt><code>interrupt_thread</code><dd><a name="index-interrupt-thread-functions-on-fido-2638"></a>Use this attribute on fido, a subarchitecture of the m68k, to indicate 756that the specified function is an interrupt handler that is designed 757to run as a thread. The compiler omits generate prologue/epilogue 758sequences and replaces the return instruction with a <code>sleep</code> 759instruction. This attribute is available only on fido. 760 761 <br><dt><code>isr</code><dd><a name="index-interrupt-service-routines-on-ARM-2639"></a>Use this attribute on ARM to write Interrupt Service Routines. This is an 762alias to the <code>interrupt</code> attribute above. 763 764 <br><dt><code>kspisusp</code><dd><a name="index-User-stack-pointer-in-interrupts-on-the-Blackfin-2640"></a>When used together with <code>interrupt_handler</code>, <code>exception_handler</code> 765or <code>nmi_handler</code>, code is generated to load the stack pointer 766from the USP register in the function prologue. 767 768 <br><dt><code>l1_text</code><dd><a name="index-g_t_0040code_007bl1_005ftext_007d-function-attribute-2641"></a>This attribute specifies a function to be placed into L1 Instruction 769SRAM. The function is put into a specific section named <code>.l1.text</code>. 770With <samp><span class="option">-mfdpic</span></samp>, function calls with a such function as the callee 771or caller uses inlined PLT. 772 773 <br><dt><code>l2</code><dd><a name="index-g_t_0040code_007bl2_007d-function-attribute-2642"></a>On the Blackfin, this attribute specifies a function to be placed into L2 774SRAM. The function is put into a specific section named 775<code>.l1.text</code>. With <samp><span class="option">-mfdpic</span></samp>, callers of such functions use 776an inlined PLT. 777 778 <br><dt><code>leaf</code><dd><a name="index-g_t_0040code_007bleaf_007d-function-attribute-2643"></a>Calls to external functions with this attribute must return to the current 779compilation unit only by return or by exception handling. In particular, leaf 780functions are not allowed to call callback function passed to it from the current 781compilation unit or directly call functions exported by the unit or longjmp 782into the unit. Leaf function might still call functions from other compilation 783units and thus they are not necessarily leaf in the sense that they contain no 784function calls at all. 785 786 <p>The attribute is intended for library functions to improve dataflow analysis. 787The compiler takes the hint that any data not escaping the current compilation unit can 788not be used or modified by the leaf function. For example, the <code>sin</code> function 789is a leaf function, but <code>qsort</code> is not. 790 791 <p>Note that leaf functions might invoke signals and signal handlers might be 792defined in the current compilation unit and use static variables. The only 793compliant way to write such a signal handler is to declare such variables 794<code>volatile</code>. 795 796 <p>The attribute has no effect on functions defined within the current compilation 797unit. This is to allow easy merging of multiple compilation units into one, 798for example, by using the link-time optimization. For this reason the 799attribute is not allowed on types to annotate indirect calls. 800 801 <br><dt><code>long_call/short_call</code><dd><a name="index-indirect-calls-on-ARM-2644"></a>This attribute specifies how a particular function is called on 802ARM and Epiphany. Both attributes override the 803<samp><span class="option">-mlong-calls</span></samp> (see <a href="ARM-Options.html#ARM-Options">ARM Options</a>) 804command-line switch and <code>#pragma long_calls</code> settings. The 805<code>long_call</code> attribute indicates that the function might be far 806away from the call site and require a different (more expensive) 807calling sequence. The <code>short_call</code> attribute always places 808the offset to the function from the call site into the ‘<samp><span class="samp">BL</span></samp>’ 809instruction directly. 810 811 <br><dt><code>longcall/shortcall</code><dd><a name="index-functions-called-via-pointer-on-the-RS_002f6000-and-PowerPC-2645"></a>On the Blackfin, RS/6000 and PowerPC, the <code>longcall</code> attribute 812indicates that the function might be far away from the call site and 813require a different (more expensive) calling sequence. The 814<code>shortcall</code> attribute indicates that the function is always close 815enough for the shorter calling sequence to be used. These attributes 816override both the <samp><span class="option">-mlongcall</span></samp> switch and, on the RS/6000 and 817PowerPC, the <code>#pragma longcall</code> setting. 818 819 <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 820calls are necessary. 821 822 <br><dt><code>long_call/near/far</code><dd><a name="index-indirect-calls-on-MIPS-2646"></a>These attributes specify how a particular function is called on MIPS. 823The attributes override the <samp><span class="option">-mlong-calls</span></samp> (see <a href="MIPS-Options.html#MIPS-Options">MIPS Options</a>) 824command-line switch. The <code>long_call</code> and <code>far</code> attributes are 825synonyms, and cause the compiler to always call 826the function by first loading its address into a register, and then using 827the contents of that register. The <code>near</code> attribute has the opposite 828effect; it specifies that non-PIC calls should be made using the more 829efficient <code>jal</code> instruction. 830 831 <br><dt><code>malloc</code><dd><a name="index-g_t_0040code_007bmalloc_007d-attribute-2647"></a>The <code>malloc</code> attribute is used to tell the compiler that a function 832may be treated as if any non-<code>NULL</code> pointer it returns cannot 833alias any other pointer valid when the function returns and that the memory 834has undefined content. 835This often improves optimization. 836Standard functions with this property include <code>malloc</code> and 837<code>calloc</code>. <code>realloc</code>-like functions do not have this 838property as the memory pointed to does not have undefined content. 839 840 <br><dt><code>mips16/nomips16</code><dd><a name="index-g_t_0040code_007bmips16_007d-attribute-2648"></a><a name="index-g_t_0040code_007bnomips16_007d-attribute-2649"></a> 841On MIPS targets, you can use the <code>mips16</code> and <code>nomips16</code> 842function attributes to locally select or turn off MIPS16 code generation. 843A function with the <code>mips16</code> attribute is emitted as MIPS16 code, 844while MIPS16 code generation is disabled for functions with the 845<code>nomips16</code> attribute. These attributes override the 846<samp><span class="option">-mips16</span></samp> and <samp><span class="option">-mno-mips16</span></samp> options on the command line 847(see <a href="MIPS-Options.html#MIPS-Options">MIPS Options</a>). 848 849 <p>When compiling files containing mixed MIPS16 and non-MIPS16 code, the 850preprocessor symbol <code>__mips16</code> reflects the setting on the command line, 851not that within individual functions. Mixed MIPS16 and non-MIPS16 code 852may interact badly with some GCC extensions such as <code>__builtin_apply</code> 853(see <a href="Constructing-Calls.html#Constructing-Calls">Constructing Calls</a>). 854 855 <br><dt><code>micromips/nomicromips</code><dd><a name="index-g_t_0040code_007bmicromips_007d-attribute-2650"></a><a name="index-g_t_0040code_007bnomicromips_007d-attribute-2651"></a> 856On MIPS targets, you can use the <code>micromips</code> and <code>nomicromips</code> 857function attributes to locally select or turn off microMIPS code generation. 858A function with the <code>micromips</code> attribute is emitted as microMIPS code, 859while microMIPS code generation is disabled for functions with the 860<code>nomicromips</code> attribute. These attributes override the 861<samp><span class="option">-mmicromips</span></samp> and <samp><span class="option">-mno-micromips</span></samp> options on the command line 862(see <a href="MIPS-Options.html#MIPS-Options">MIPS Options</a>). 863 864 <p>When compiling files containing mixed microMIPS and non-microMIPS code, the 865preprocessor symbol <code>__mips_micromips</code> reflects the setting on the 866command line, 867not that within individual functions. Mixed microMIPS and non-microMIPS code 868may interact badly with some GCC extensions such as <code>__builtin_apply</code> 869(see <a href="Constructing-Calls.html#Constructing-Calls">Constructing Calls</a>). 870 871 <br><dt><code>model (</code><var>model-name</var><code>)</code><dd><a name="index-function-addressability-on-the-M32R_002fD-2652"></a><a name="index-variable-addressability-on-the-IA_002d64-2653"></a> 872On the M32R/D, use this attribute to set the addressability of an 873object, and of the code generated for a function. The identifier 874<var>model-name</var> is one of <code>small</code>, <code>medium</code>, or 875<code>large</code>, representing each of the code models. 876 877 <p>Small model objects live in the lower 16MB of memory (so that their 878addresses can be loaded with the <code>ld24</code> instruction), and are 879callable with the <code>bl</code> instruction. 880 881 <p>Medium model objects may live anywhere in the 32-bit address space (the 882compiler generates <code>seth/add3</code> instructions to load their addresses), 883and are callable with the <code>bl</code> instruction. 884 885 <p>Large model objects may live anywhere in the 32-bit address space (the 886compiler generates <code>seth/add3</code> instructions to load their addresses), 887and may not be reachable with the <code>bl</code> instruction (the compiler 888generates the much slower <code>seth/add3/jl</code> instruction sequence). 889 890 <p>On IA-64, use this attribute to set the addressability of an object. 891At present, the only supported identifier for <var>model-name</var> is 892<code>small</code>, indicating addressability via “small” (22-bit) 893addresses (so that their addresses can be loaded with the <code>addl</code> 894instruction). Caveat: such addressing is by definition not position 895independent and hence this attribute must not be used for objects 896defined by shared libraries. 897 898 <br><dt><code>ms_abi/sysv_abi</code><dd><a name="index-g_t_0040code_007bms_005fabi_007d-attribute-2654"></a><a name="index-g_t_0040code_007bsysv_005fabi_007d-attribute-2655"></a> 899On 32-bit and 64-bit (i?86|x86_64)-*-* targets, you can use an ABI attribute 900to indicate which calling convention should be used for a function. The 901<code>ms_abi</code> attribute tells the compiler to use the Microsoft ABI, 902while the <code>sysv_abi</code> attribute tells the compiler to use the ABI 903used on GNU/Linux and other systems. The default is to use the Microsoft ABI 904when targeting Windows. On all other systems, the default is the x86/AMD ABI. 905 906 <p>Note, the <code>ms_abi</code> attribute for Microsoft Windows 64-bit targets currently 907requires the <samp><span class="option">-maccumulate-outgoing-args</span></samp> option. 908 909 <br><dt><code>callee_pop_aggregate_return (</code><var>number</var><code>)</code><dd><a name="index-g_t_0040code_007bcallee_005fpop_005faggregate_005freturn_007d-attribute-2656"></a> 910On 32-bit i?86-*-* targets, you can use this attribute to control how 911aggregates are returned in memory. If the caller is responsible for 912popping the hidden pointer together with the rest of the arguments, specify 913<var>number</var> equal to zero. If callee is responsible for popping the 914hidden pointer, specify <var>number</var> equal to one. 915 916 <p>The default i386 ABI assumes that the callee pops the 917stack for hidden pointer. However, on 32-bit i386 Microsoft Windows targets, 918the compiler assumes that the 919caller pops the stack for hidden pointer. 920 921 <br><dt><code>ms_hook_prologue</code><dd><a name="index-g_t_0040code_007bms_005fhook_005fprologue_007d-attribute-2657"></a> 922On 32-bit i[34567]86-*-* targets and 64-bit x86_64-*-* targets, you can use 923this function attribute to make GCC generate the “hot-patching” function 924prologue used in Win32 API functions in Microsoft Windows XP Service Pack 2 925and newer. 926 927 <br><dt><code>naked</code><dd><a name="index-function-without-a-prologue_002fepilogue-code-2658"></a>Use this attribute on the ARM, AVR, MCORE, RX and SPU ports to indicate that 928the specified function does not need prologue/epilogue sequences generated by 929the compiler. It is up to the programmer to provide these sequences. The 930only statements that can be safely included in naked functions are 931<code>asm</code> statements that do not have operands. All other statements, 932including declarations of local variables, <code>if</code> statements, and so 933forth, should be avoided. Naked functions should be used to implement the 934body of an assembly function, while allowing the compiler to construct 935the requisite function declaration for the assembler. 936 937 <br><dt><code>near</code><dd><a name="index-functions-that-do-not-handle-memory-bank-switching-on-68HC11_002f68HC12-2659"></a>On 68HC11 and 68HC12 the <code>near</code> attribute causes the compiler to 938use the normal calling convention based on <code>jsr</code> and <code>rts</code>. 939This attribute can be used to cancel the effect of the <samp><span class="option">-mlong-calls</span></samp> 940option. 941 942 <p>On MeP targets this attribute causes the compiler to assume the called 943function is close enough to use the normal calling convention, 944overriding the <samp><span class="option">-mtf</span></samp> command-line option. 945 946 <br><dt><code>nesting</code><dd><a name="index-Allow-nesting-in-an-interrupt-handler-on-the-Blackfin-processor_002e-2660"></a>Use this attribute together with <code>interrupt_handler</code>, 947<code>exception_handler</code> or <code>nmi_handler</code> to indicate that the function 948entry code should enable nested interrupts or exceptions. 949 950 <br><dt><code>nmi_handler</code><dd><a name="index-NMI-handler-functions-on-the-Blackfin-processor-2661"></a>Use this attribute on the Blackfin to indicate that the specified function 951is an NMI handler. The compiler generates function entry and 952exit sequences suitable for use in an NMI handler when this 953attribute is present. 954 955 <br><dt><code>nocompression</code><dd><a name="index-g_t_0040code_007bnocompression_007d-attribute-2662"></a>On MIPS targets, you can use the <code>nocompression</code> function attribute 956to locally turn off MIPS16 and microMIPS code generation. This attribute 957overrides the <samp><span class="option">-mips16</span></samp> and <samp><span class="option">-mmicromips</span></samp> options on the 958command line (see <a href="MIPS-Options.html#MIPS-Options">MIPS Options</a>). 959 960 <br><dt><code>no_instrument_function</code><dd><a name="index-g_t_0040code_007bno_005finstrument_005ffunction_007d-function-attribute-2663"></a><a name="index-finstrument_002dfunctions-2664"></a>If <samp><span class="option">-finstrument-functions</span></samp> is given, profiling function calls are 961generated at entry and exit of most user-compiled functions. 962Functions with this attribute are not so instrumented. 963 964 <br><dt><code>no_split_stack</code><dd><a name="index-g_t_0040code_007bno_005fsplit_005fstack_007d-function-attribute-2665"></a><a name="index-fsplit_002dstack-2666"></a>If <samp><span class="option">-fsplit-stack</span></samp> is given, functions have a small 965prologue which decides whether to split the stack. Functions with the 966<code>no_split_stack</code> attribute do not have that prologue, and thus 967may run with only a small amount of stack space available. 968 969 <br><dt><code>noinline</code><dd><a name="index-g_t_0040code_007bnoinline_007d-function-attribute-2667"></a>This function attribute prevents a function from being considered for 970inlining. 971<!-- Don't enumerate the optimizations by name here; we try to be --> 972<!-- future-compatible with this mechanism. --> 973If the function does not have side-effects, there are optimizations 974other than inlining that cause function calls to be optimized away, 975although the function call is live. To keep such calls from being 976optimized away, put 977 <pre class="smallexample"> asm (""); 978</pre> 979 <p class="noindent">(see <a href="Extended-Asm.html#Extended-Asm">Extended Asm</a>) in the called function, to serve as a special 980side-effect. 981 982 <br><dt><code>noclone</code><dd><a name="index-g_t_0040code_007bnoclone_007d-function-attribute-2668"></a>This function attribute prevents a function from being considered for 983cloning—a mechanism that produces specialized copies of functions 984and which is (currently) performed by interprocedural constant 985propagation. 986 987 <br><dt><code>nonnull (</code><var>arg-index</var><code>, ...)</code><dd><a name="index-g_t_0040code_007bnonnull_007d-function-attribute-2669"></a>The <code>nonnull</code> attribute specifies that some function parameters should 988be non-null pointers. For instance, the declaration: 989 990 <pre class="smallexample"> extern void * 991 my_memcpy (void *dest, const void *src, size_t len) 992 __attribute__((nonnull (1, 2))); 993</pre> 994 <p class="noindent">causes the compiler to check that, in calls to <code>my_memcpy</code>, 995arguments <var>dest</var> and <var>src</var> are non-null. If the compiler 996determines that a null pointer is passed in an argument slot marked 997as non-null, and the <samp><span class="option">-Wnonnull</span></samp> option is enabled, a warning 998is issued. The compiler may also choose to make optimizations based 999on the knowledge that certain function arguments will never be null. 1000 1001 <p>If no argument index list is given to the <code>nonnull</code> attribute, 1002all pointer arguments are marked as non-null. To illustrate, the 1003following declaration is equivalent to the previous example: 1004 1005 <pre class="smallexample"> extern void * 1006 my_memcpy (void *dest, const void *src, size_t len) 1007 __attribute__((nonnull)); 1008</pre> 1009 <br><dt><code>noreturn</code><dd><a name="index-g_t_0040code_007bnoreturn_007d-function-attribute-2670"></a>A few standard library functions, such as <code>abort</code> and <code>exit</code>, 1010cannot return. GCC knows this automatically. Some programs define 1011their own functions that never return. You can declare them 1012<code>noreturn</code> to tell the compiler this fact. For example, 1013 1014 <pre class="smallexample"> void fatal () __attribute__ ((noreturn)); 1015 1016 void 1017 fatal (/* <span class="roman">...</span> */) 1018 { 1019 /* <span class="roman">...</span> */ /* <span class="roman">Print error message.</span> */ /* <span class="roman">...</span> */ 1020 exit (1); 1021 } 1022</pre> 1023 <p>The <code>noreturn</code> keyword tells the compiler to assume that 1024<code>fatal</code> cannot return. It can then optimize without regard to what 1025would happen if <code>fatal</code> ever did return. This makes slightly 1026better code. More importantly, it helps avoid spurious warnings of 1027uninitialized variables. 1028 1029 <p>The <code>noreturn</code> keyword does not affect the exceptional path when that 1030applies: a <code>noreturn</code>-marked function may still return to the caller 1031by throwing an exception or calling <code>longjmp</code>. 1032 1033 <p>Do not assume that registers saved by the calling function are 1034restored before calling the <code>noreturn</code> function. 1035 1036 <p>It does not make sense for a <code>noreturn</code> function to have a return 1037type other than <code>void</code>. 1038 1039 <p>The attribute <code>noreturn</code> is not implemented in GCC versions 1040earlier than 2.5. An alternative way to declare that a function does 1041not return, which works in the current version and in some older 1042versions, is as follows: 1043 1044 <pre class="smallexample"> typedef void voidfn (); 1045 1046 volatile voidfn fatal; 1047</pre> 1048 <p class="noindent">This approach does not work in GNU C++. 1049 1050 <br><dt><code>nothrow</code><dd><a name="index-g_t_0040code_007bnothrow_007d-function-attribute-2671"></a>The <code>nothrow</code> attribute is used to inform the compiler that a 1051function cannot throw an exception. For example, most functions in 1052the standard C library can be guaranteed not to throw an exception 1053with the notable exceptions of <code>qsort</code> and <code>bsearch</code> that 1054take function pointer arguments. The <code>nothrow</code> attribute is not 1055implemented in GCC versions earlier than 3.3. 1056 1057 <br><dt><code>nosave_low_regs</code><dd><a name="index-g_t_0040code_007bnosave_005flow_005fregs_007d-attribute-2672"></a>Use this attribute on SH targets to indicate that an <code>interrupt_handler</code> 1058function should not save and restore registers R0..R7. This can be used on SH3* 1059and SH4* targets that have a second R0..R7 register bank for non-reentrant 1060interrupt handlers. 1061 1062 <br><dt><code>optimize</code><dd><a name="index-g_t_0040code_007boptimize_007d-function-attribute-2673"></a>The <code>optimize</code> attribute is used to specify that a function is to 1063be compiled with different optimization options than specified on the 1064command line. Arguments can either be numbers or strings. Numbers 1065are assumed to be an optimization level. Strings that begin with 1066<code>O</code> are assumed to be an optimization option, while other options 1067are assumed to be used with a <code>-f</code> prefix. You can also use the 1068‘<samp><span class="samp">#pragma GCC optimize</span></samp>’ pragma to set the optimization options 1069that affect more than one function. 1070See <a href="Function-Specific-Option-Pragmas.html#Function-Specific-Option-Pragmas">Function Specific Option Pragmas</a>, for details about the 1071‘<samp><span class="samp">#pragma GCC optimize</span></samp>’ pragma. 1072 1073 <p>This can be used for instance to have frequently-executed functions 1074compiled with more aggressive optimization options that produce faster 1075and larger code, while other functions can be compiled with less 1076aggressive options. 1077 1078 <br><dt><code>OS_main/OS_task</code><dd><a name="index-g_t_0040code_007bOS_005fmain_007d-AVR-function-attribute-2674"></a><a name="index-g_t_0040code_007bOS_005ftask_007d-AVR-function-attribute-2675"></a>On AVR, functions with the <code>OS_main</code> or <code>OS_task</code> attribute 1079do not save/restore any call-saved register in their prologue/epilogue. 1080 1081 <p>The <code>OS_main</code> attribute can be used when there <em>is 1082guarantee</em> that interrupts are disabled at the time when the function 1083is entered. This saves resources when the stack pointer has to be 1084changed to set up a frame for local variables. 1085 1086 <p>The <code>OS_task</code> attribute can be used when there is <em>no 1087guarantee</em> that interrupts are disabled at that time when the function 1088is entered like for, e.g. task functions in a multi-threading operating 1089system. In that case, changing the stack pointer register is 1090guarded by save/clear/restore of the global interrupt enable flag. 1091 1092 <p>The differences to the <code>naked</code> function attribute are: 1093 <ul> 1094<li><code>naked</code> functions do not have a return instruction whereas 1095<code>OS_main</code> and <code>OS_task</code> functions have a <code>RET</code> or 1096<code>RETI</code> return instruction. 1097<li><code>naked</code> functions do not set up a frame for local variables 1098or a frame pointer whereas <code>OS_main</code> and <code>OS_task</code> do this 1099as needed. 1100</ul> 1101 1102 <br><dt><code>pcs</code><dd><a name="index-g_t_0040code_007bpcs_007d-function-attribute-2676"></a> 1103The <code>pcs</code> attribute can be used to control the calling convention 1104used for a function on ARM. The attribute takes an argument that specifies 1105the calling convention to use. 1106 1107 <p>When compiling using the AAPCS ABI (or a variant of it) then valid 1108values for the argument are <code>"aapcs"</code> and <code>"aapcs-vfp"</code>. In 1109order to use a variant other than <code>"aapcs"</code> then the compiler must 1110be permitted to use the appropriate co-processor registers (i.e., the 1111VFP registers must be available in order to use <code>"aapcs-vfp"</code>). 1112For example, 1113 1114 <pre class="smallexample"> /* Argument passed in r0, and result returned in r0+r1. */ 1115 double f2d (float) __attribute__((pcs("aapcs"))); 1116</pre> 1117 <p>Variadic functions always use the <code>"aapcs"</code> calling convention and 1118the compiler rejects attempts to specify an alternative. 1119 1120 <br><dt><code>pure</code><dd><a name="index-g_t_0040code_007bpure_007d-function-attribute-2677"></a>Many functions have no effects except the return value and their 1121return value depends only on the parameters and/or global variables. 1122Such a function can be subject 1123to common subexpression elimination and loop optimization just as an 1124arithmetic operator would be. These functions should be declared 1125with the attribute <code>pure</code>. For example, 1126 1127 <pre class="smallexample"> int square (int) __attribute__ ((pure)); 1128</pre> 1129 <p class="noindent">says that the hypothetical function <code>square</code> is safe to call 1130fewer times than the program says. 1131 1132 <p>Some of common examples of pure functions are <code>strlen</code> or <code>memcmp</code>. 1133Interesting non-pure functions are functions with infinite loops or those 1134depending on volatile memory or other system resource, that may change between 1135two consecutive calls (such as <code>feof</code> in a multithreading environment). 1136 1137 <p>The attribute <code>pure</code> is not implemented in GCC versions earlier 1138than 2.96. 1139 1140 <br><dt><code>hot</code><dd><a name="index-g_t_0040code_007bhot_007d-function-attribute-2678"></a>The <code>hot</code> attribute on a function is used to inform the compiler that 1141the function is a hot spot of the compiled program. The function is 1142optimized more aggressively and on many target it is placed into special 1143subsection of the text section so all hot functions appears close together 1144improving locality. 1145 1146 <p>When profile feedback is available, via <samp><span class="option">-fprofile-use</span></samp>, hot functions 1147are automatically detected and this attribute is ignored. 1148 1149 <p>The <code>hot</code> attribute on functions is not implemented in GCC versions 1150earlier than 4.3. 1151 1152 <p><a name="index-g_t_0040code_007bhot_007d-label-attribute-2679"></a>The <code>hot</code> attribute on a label is used to inform the compiler that 1153path following the label are more likely than paths that are not so 1154annotated. This attribute is used in cases where <code>__builtin_expect</code> 1155cannot be used, for instance with computed goto or <code>asm goto</code>. 1156 1157 <p>The <code>hot</code> attribute on labels is not implemented in GCC versions 1158earlier than 4.8. 1159 1160 <br><dt><code>cold</code><dd><a name="index-g_t_0040code_007bcold_007d-function-attribute-2680"></a>The <code>cold</code> attribute on functions is used to inform the compiler that 1161the function is unlikely to be executed. The function is optimized for 1162size rather than speed and on many targets it is placed into special 1163subsection of the text section so all cold functions appears close together 1164improving code locality of non-cold parts of program. The paths leading 1165to call of cold functions within code are marked as unlikely by the branch 1166prediction mechanism. It is thus useful to mark functions used to handle 1167unlikely conditions, such as <code>perror</code>, as cold to improve optimization 1168of hot functions that do call marked functions in rare occasions. 1169 1170 <p>When profile feedback is available, via <samp><span class="option">-fprofile-use</span></samp>, cold functions 1171are automatically detected and this attribute is ignored. 1172 1173 <p>The <code>cold</code> attribute on functions is not implemented in GCC versions 1174earlier than 4.3. 1175 1176 <p><a name="index-g_t_0040code_007bcold_007d-label-attribute-2681"></a>The <code>cold</code> attribute on labels is used to inform the compiler that 1177the path following the label is unlikely to be executed. This attribute 1178is used in cases where <code>__builtin_expect</code> cannot be used, for instance 1179with computed goto or <code>asm goto</code>. 1180 1181 <p>The <code>cold</code> attribute on labels is not implemented in GCC versions 1182earlier than 4.8. 1183 1184 <br><dt><code>no_sanitize_address</code><dt><code>no_address_safety_analysis</code><dd><a name="index-g_t_0040code_007bno_005fsanitize_005faddress_007d-function-attribute-2682"></a>The <code>no_sanitize_address</code> attribute on functions is used 1185to inform the compiler that it should not instrument memory accesses 1186in the function when compiling with the <samp><span class="option">-fsanitize=address</span></samp> option. 1187The <code>no_address_safety_analysis</code> is a deprecated alias of the 1188<code>no_sanitize_address</code> attribute, new code should use 1189<code>no_sanitize_address</code>. 1190 1191 <br><dt><code>regparm (</code><var>number</var><code>)</code><dd><a name="index-g_t_0040code_007bregparm_007d-attribute-2683"></a><a name="index-functions-that-are-passed-arguments-in-registers-on-the-386-2684"></a>On the Intel 386, the <code>regparm</code> attribute causes the compiler to 1192pass arguments number one to <var>number</var> if they are of integral type 1193in registers EAX, EDX, and ECX instead of on the stack. Functions that 1194take a variable number of arguments continue to be passed all of their 1195arguments on the stack. 1196 1197 <p>Beware that on some ELF systems this attribute is unsuitable for 1198global functions in shared libraries with lazy binding (which is the 1199default). Lazy binding sends the first call via resolving code in 1200the loader, which might assume EAX, EDX and ECX can be clobbered, as 1201per the standard calling conventions. Solaris 8 is affected by this. 1202Systems with the GNU C Library version 2.1 or higher 1203and FreeBSD are believed to be 1204safe since the loaders there save EAX, EDX and ECX. (Lazy binding can be 1205disabled with the linker or the loader if desired, to avoid the 1206problem.) 1207 1208 <br><dt><code>sseregparm</code><dd><a name="index-g_t_0040code_007bsseregparm_007d-attribute-2685"></a>On the Intel 386 with SSE support, the <code>sseregparm</code> attribute 1209causes the compiler to pass up to 3 floating-point arguments in 1210SSE registers instead of on the stack. Functions that take a 1211variable number of arguments continue to pass all of their 1212floating-point arguments on the stack. 1213 1214 <br><dt><code>force_align_arg_pointer</code><dd><a name="index-g_t_0040code_007bforce_005falign_005farg_005fpointer_007d-attribute-2686"></a>On the Intel x86, the <code>force_align_arg_pointer</code> attribute may be 1215applied to individual function definitions, generating an alternate 1216prologue and epilogue that realigns the run-time stack if necessary. 1217This supports mixing legacy codes that run with a 4-byte aligned stack 1218with modern codes that keep a 16-byte stack for SSE compatibility. 1219 1220 <br><dt><code>renesas</code><dd><a name="index-g_t_0040code_007brenesas_007d-attribute-2687"></a>On SH targets this attribute specifies that the function or struct follows the 1221Renesas ABI. 1222 1223 <br><dt><code>resbank</code><dd><a name="index-g_t_0040code_007bresbank_007d-attribute-2688"></a>On the SH2A target, this attribute enables the high-speed register 1224saving and restoration using a register bank for <code>interrupt_handler</code> 1225routines. Saving to the bank is performed automatically after the CPU 1226accepts an interrupt that uses a register bank. 1227 1228 <p>The nineteen 32-bit registers comprising general register R0 to R14, 1229control register GBR, and system registers MACH, MACL, and PR and the 1230vector table address offset are saved into a register bank. Register 1231banks are stacked in first-in last-out (FILO) sequence. Restoration 1232from the bank is executed by issuing a RESBANK instruction. 1233 1234 <br><dt><code>returns_twice</code><dd><a name="index-g_t_0040code_007breturns_005ftwice_007d-attribute-2689"></a>The <code>returns_twice</code> attribute tells the compiler that a function may 1235return more than one time. The compiler ensures that all registers 1236are dead before calling such a function and emits a warning about 1237the variables that may be clobbered after the second return from the 1238function. Examples of such functions are <code>setjmp</code> and <code>vfork</code>. 1239The <code>longjmp</code>-like counterpart of such function, if any, might need 1240to be marked with the <code>noreturn</code> attribute. 1241 1242 <br><dt><code>saveall</code><dd><a name="index-save-all-registers-on-the-Blackfin_002c-H8_002f300_002c-H8_002f300H_002c-and-H8S-2690"></a>Use this attribute on the Blackfin, H8/300, H8/300H, and H8S to indicate that 1243all registers except the stack pointer should be saved in the prologue 1244regardless of whether they are used or not. 1245 1246 <br><dt><code>save_volatiles</code><dd><a name="index-save-volatile-registers-on-the-MicroBlaze-2691"></a>Use this attribute on the MicroBlaze to indicate that the function is 1247an interrupt handler. All volatile registers (in addition to non-volatile 1248registers) are saved in the function prologue. If the function is a leaf 1249function, only volatiles used by the function are saved. A normal function 1250return is generated instead of a return from interrupt. 1251 1252 <br><dt><code>section ("</code><var>section-name</var><code>")</code><dd><a name="index-g_t_0040code_007bsection_007d-function-attribute-2692"></a>Normally, the compiler places the code it generates in the <code>text</code> section. 1253Sometimes, however, you need additional sections, or you need certain 1254particular functions to appear in special sections. The <code>section</code> 1255attribute specifies that a function lives in a particular section. 1256For example, the declaration: 1257 1258 <pre class="smallexample"> extern void foobar (void) __attribute__ ((section ("bar"))); 1259</pre> 1260 <p class="noindent">puts the function <code>foobar</code> in the <code>bar</code> section. 1261 1262 <p>Some file formats do not support arbitrary sections so the <code>section</code> 1263attribute is not available on all platforms. 1264If you need to map the entire contents of a module to a particular 1265section, consider using the facilities of the linker instead. 1266 1267 <br><dt><code>sentinel</code><dd><a name="index-g_t_0040code_007bsentinel_007d-function-attribute-2693"></a>This function attribute ensures that a parameter in a function call is 1268an explicit <code>NULL</code>. The attribute is only valid on variadic 1269functions. By default, the sentinel is located at position zero, the 1270last parameter of the function call. If an optional integer position 1271argument P is supplied to the attribute, the sentinel must be located at 1272position P counting backwards from the end of the argument list. 1273 1274 <pre class="smallexample"> __attribute__ ((sentinel)) 1275 is equivalent to 1276 __attribute__ ((sentinel(0))) 1277</pre> 1278 <p>The attribute is automatically set with a position of 0 for the built-in 1279functions <code>execl</code> and <code>execlp</code>. The built-in function 1280<code>execle</code> has the attribute set with a position of 1. 1281 1282 <p>A valid <code>NULL</code> in this context is defined as zero with any pointer 1283type. If your system defines the <code>NULL</code> macro with an integer type 1284then you need to add an explicit cast. GCC replaces <code>stddef.h</code> 1285with a copy that redefines NULL appropriately. 1286 1287 <p>The warnings for missing or incorrect sentinels are enabled with 1288<samp><span class="option">-Wformat</span></samp>. 1289 1290 <br><dt><code>short_call</code><dd>See <code>long_call/short_call</code>. 1291 1292 <br><dt><code>shortcall</code><dd>See <code>longcall/shortcall</code>. 1293 1294 <br><dt><code>signal</code><dd><a name="index-interrupt-handler-functions-on-the-AVR-processors-2694"></a>Use this attribute on the AVR to indicate that the specified 1295function is an interrupt handler. The compiler generates function 1296entry and exit sequences suitable for use in an interrupt handler when this 1297attribute is present. 1298 1299 <p>See also the <code>interrupt</code> function attribute. 1300 1301 <p>The AVR hardware globally disables interrupts when an interrupt is executed. 1302Interrupt handler functions defined with the <code>signal</code> attribute 1303do not re-enable interrupts. It is save to enable interrupts in a 1304<code>signal</code> handler. This “save” only applies to the code 1305generated by the compiler and not to the IRQ layout of the 1306application which is responsibility of the application. 1307 1308 <p>If both <code>signal</code> and <code>interrupt</code> are specified for the same 1309function, <code>signal</code> is silently ignored. 1310 1311 <br><dt><code>sp_switch</code><dd><a name="index-g_t_0040code_007bsp_005fswitch_007d-attribute-2695"></a>Use this attribute on the SH to indicate an <code>interrupt_handler</code> 1312function should switch to an alternate stack. It expects a string 1313argument that names a global variable holding the address of the 1314alternate stack. 1315 1316 <pre class="smallexample"> void *alt_stack; 1317 void f () __attribute__ ((interrupt_handler, 1318 sp_switch ("alt_stack"))); 1319</pre> 1320 <br><dt><code>stdcall</code><dd><a name="index-functions-that-pop-the-argument-stack-on-the-386-2696"></a>On the Intel 386, the <code>stdcall</code> attribute causes the compiler to 1321assume that the called function pops off the stack space used to 1322pass arguments, unless it takes a variable number of arguments. 1323 1324 <br><dt><code>syscall_linkage</code><dd><a name="index-g_t_0040code_007bsyscall_005flinkage_007d-attribute-2697"></a>This attribute is used to modify the IA-64 calling convention by marking 1325all input registers as live at all function exits. This makes it possible 1326to restart a system call after an interrupt without having to save/restore 1327the input registers. This also prevents kernel data from leaking into 1328application code. 1329 1330 <br><dt><code>target</code><dd><a name="index-g_t_0040code_007btarget_007d-function-attribute-2698"></a>The <code>target</code> attribute is used to specify that a function is to 1331be compiled with different target options than specified on the 1332command line. This can be used for instance to have functions 1333compiled with a different ISA (instruction set architecture) than the 1334default. You can also use the ‘<samp><span class="samp">#pragma GCC target</span></samp>’ pragma to set 1335more than one function to be compiled with specific target options. 1336See <a href="Function-Specific-Option-Pragmas.html#Function-Specific-Option-Pragmas">Function Specific Option Pragmas</a>, for details about the 1337‘<samp><span class="samp">#pragma GCC target</span></samp>’ pragma. 1338 1339 <p>For instance on a 386, you could compile one function with 1340<code>target("sse4.1,arch=core2")</code> and another with 1341<code>target("sse4a,arch=amdfam10")</code>. This is equivalent to 1342compiling the first function with <samp><span class="option">-msse4.1</span></samp> and 1343<samp><span class="option">-march=core2</span></samp> options, and the second function with 1344<samp><span class="option">-msse4a</span></samp> and <samp><span class="option">-march=amdfam10</span></samp> options. It is up to the 1345user to make sure that a function is only invoked on a machine that 1346supports the particular ISA it is compiled for (for example by using 1347<code>cpuid</code> on 386 to determine what feature bits and architecture 1348family are used). 1349 1350 <pre class="smallexample"> int core2_func (void) __attribute__ ((__target__ ("arch=core2"))); 1351 int sse3_func (void) __attribute__ ((__target__ ("sse3"))); 1352</pre> 1353 <p>On the 386, the following options are allowed: 1354 1355 <dl> 1356<dt>‘<samp><span class="samp">abm</span></samp>’<dt>‘<samp><span class="samp">no-abm</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022abm_0022_0029_007d-attribute-2699"></a>Enable/disable the generation of the advanced bit instructions. 1357 1358 <br><dt>‘<samp><span class="samp">aes</span></samp>’<dt>‘<samp><span class="samp">no-aes</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022aes_0022_0029_007d-attribute-2700"></a>Enable/disable the generation of the AES instructions. 1359 1360 <br><dt>‘<samp><span class="samp">default</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022default_0022_0029_007d-attribute-2701"></a>See <a href="Function-Multiversioning.html#Function-Multiversioning">Function Multiversioning</a>, where it is used to specify the 1361default function version. 1362 1363 <br><dt>‘<samp><span class="samp">mmx</span></samp>’<dt>‘<samp><span class="samp">no-mmx</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022mmx_0022_0029_007d-attribute-2702"></a>Enable/disable the generation of the MMX instructions. 1364 1365 <br><dt>‘<samp><span class="samp">pclmul</span></samp>’<dt>‘<samp><span class="samp">no-pclmul</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022pclmul_0022_0029_007d-attribute-2703"></a>Enable/disable the generation of the PCLMUL instructions. 1366 1367 <br><dt>‘<samp><span class="samp">popcnt</span></samp>’<dt>‘<samp><span class="samp">no-popcnt</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022popcnt_0022_0029_007d-attribute-2704"></a>Enable/disable the generation of the POPCNT instruction. 1368 1369 <br><dt>‘<samp><span class="samp">sse</span></samp>’<dt>‘<samp><span class="samp">no-sse</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022sse_0022_0029_007d-attribute-2705"></a>Enable/disable the generation of the SSE instructions. 1370 1371 <br><dt>‘<samp><span class="samp">sse2</span></samp>’<dt>‘<samp><span class="samp">no-sse2</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022sse2_0022_0029_007d-attribute-2706"></a>Enable/disable the generation of the SSE2 instructions. 1372 1373 <br><dt>‘<samp><span class="samp">sse3</span></samp>’<dt>‘<samp><span class="samp">no-sse3</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022sse3_0022_0029_007d-attribute-2707"></a>Enable/disable the generation of the SSE3 instructions. 1374 1375 <br><dt>‘<samp><span class="samp">sse4</span></samp>’<dt>‘<samp><span class="samp">no-sse4</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022sse4_0022_0029_007d-attribute-2708"></a>Enable/disable the generation of the SSE4 instructions (both SSE4.1 1376and SSE4.2). 1377 1378 <br><dt>‘<samp><span class="samp">sse4.1</span></samp>’<dt>‘<samp><span class="samp">no-sse4.1</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022sse4_002e1_0022_0029_007d-attribute-2709"></a>Enable/disable the generation of the sse4.1 instructions. 1379 1380 <br><dt>‘<samp><span class="samp">sse4.2</span></samp>’<dt>‘<samp><span class="samp">no-sse4.2</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022sse4_002e2_0022_0029_007d-attribute-2710"></a>Enable/disable the generation of the sse4.2 instructions. 1381 1382 <br><dt>‘<samp><span class="samp">sse4a</span></samp>’<dt>‘<samp><span class="samp">no-sse4a</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022sse4a_0022_0029_007d-attribute-2711"></a>Enable/disable the generation of the SSE4A instructions. 1383 1384 <br><dt>‘<samp><span class="samp">fma4</span></samp>’<dt>‘<samp><span class="samp">no-fma4</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022fma4_0022_0029_007d-attribute-2712"></a>Enable/disable the generation of the FMA4 instructions. 1385 1386 <br><dt>‘<samp><span class="samp">xop</span></samp>’<dt>‘<samp><span class="samp">no-xop</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022xop_0022_0029_007d-attribute-2713"></a>Enable/disable the generation of the XOP instructions. 1387 1388 <br><dt>‘<samp><span class="samp">lwp</span></samp>’<dt>‘<samp><span class="samp">no-lwp</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022lwp_0022_0029_007d-attribute-2714"></a>Enable/disable the generation of the LWP instructions. 1389 1390 <br><dt>‘<samp><span class="samp">ssse3</span></samp>’<dt>‘<samp><span class="samp">no-ssse3</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022ssse3_0022_0029_007d-attribute-2715"></a>Enable/disable the generation of the SSSE3 instructions. 1391 1392 <br><dt>‘<samp><span class="samp">cld</span></samp>’<dt>‘<samp><span class="samp">no-cld</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022cld_0022_0029_007d-attribute-2716"></a>Enable/disable the generation of the CLD before string moves. 1393 1394 <br><dt>‘<samp><span class="samp">fancy-math-387</span></samp>’<dt>‘<samp><span class="samp">no-fancy-math-387</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022fancy_002dmath_002d387_0022_0029_007d-attribute-2717"></a>Enable/disable the generation of the <code>sin</code>, <code>cos</code>, and 1395<code>sqrt</code> instructions on the 387 floating-point unit. 1396 1397 <br><dt>‘<samp><span class="samp">fused-madd</span></samp>’<dt>‘<samp><span class="samp">no-fused-madd</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022fused_002dmadd_0022_0029_007d-attribute-2718"></a>Enable/disable the generation of the fused multiply/add instructions. 1398 1399 <br><dt>‘<samp><span class="samp">ieee-fp</span></samp>’<dt>‘<samp><span class="samp">no-ieee-fp</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022ieee_002dfp_0022_0029_007d-attribute-2719"></a>Enable/disable the generation of floating point that depends on IEEE arithmetic. 1400 1401 <br><dt>‘<samp><span class="samp">inline-all-stringops</span></samp>’<dt>‘<samp><span class="samp">no-inline-all-stringops</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022inline_002dall_002dstringops_0022_0029_007d-attribute-2720"></a>Enable/disable inlining of string operations. 1402 1403 <br><dt>‘<samp><span class="samp">inline-stringops-dynamically</span></samp>’<dt>‘<samp><span class="samp">no-inline-stringops-dynamically</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022inline_002dstringops_002ddynamically_0022_0029_007d-attribute-2721"></a>Enable/disable the generation of the inline code to do small string 1404operations and calling the library routines for large operations. 1405 1406 <br><dt>‘<samp><span class="samp">align-stringops</span></samp>’<dt>‘<samp><span class="samp">no-align-stringops</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022align_002dstringops_0022_0029_007d-attribute-2722"></a>Do/do not align destination of inlined string operations. 1407 1408 <br><dt>‘<samp><span class="samp">recip</span></samp>’<dt>‘<samp><span class="samp">no-recip</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022recip_0022_0029_007d-attribute-2723"></a>Enable/disable the generation of RCPSS, RCPPS, RSQRTSS and RSQRTPS 1409instructions followed an additional Newton-Raphson step instead of 1410doing a floating-point division. 1411 1412 <br><dt>‘<samp><span class="samp">arch=</span><var>ARCH</var></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022arch_003d_0040var_007bARCH_007d_0022_0029_007d-attribute-2724"></a>Specify the architecture to generate code for in compiling the function. 1413 1414 <br><dt>‘<samp><span class="samp">tune=</span><var>TUNE</var></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022tune_003d_0040var_007bTUNE_007d_0022_0029_007d-attribute-2725"></a>Specify the architecture to tune for in compiling the function. 1415 1416 <br><dt>‘<samp><span class="samp">fpmath=</span><var>FPMATH</var></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022fpmath_003d_0040var_007bFPMATH_007d_0022_0029_007d-attribute-2726"></a>Specify which floating-point unit to use. The 1417<code>target("fpmath=sse,387")</code> option must be specified as 1418<code>target("fpmath=sse+387")</code> because the comma would separate 1419different options. 1420</dl> 1421 1422 <p>On the PowerPC, the following options are allowed: 1423 1424 <dl> 1425<dt>‘<samp><span class="samp">altivec</span></samp>’<dt>‘<samp><span class="samp">no-altivec</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022altivec_0022_0029_007d-attribute-2727"></a>Generate code that uses (does not use) AltiVec instructions. In 142632-bit code, you cannot enable AltiVec instructions unless 1427<samp><span class="option">-mabi=altivec</span></samp> is used on the command line. 1428 1429 <br><dt>‘<samp><span class="samp">cmpb</span></samp>’<dt>‘<samp><span class="samp">no-cmpb</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022cmpb_0022_0029_007d-attribute-2728"></a>Generate code that uses (does not use) the compare bytes instruction 1430implemented on the POWER6 processor and other processors that support 1431the PowerPC V2.05 architecture. 1432 1433 <br><dt>‘<samp><span class="samp">dlmzb</span></samp>’<dt>‘<samp><span class="samp">no-dlmzb</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022dlmzb_0022_0029_007d-attribute-2729"></a>Generate code that uses (does not use) the string-search ‘<samp><span class="samp">dlmzb</span></samp>’ 1434instruction on the IBM 405, 440, 464 and 476 processors. This instruction is 1435generated by default when targeting those processors. 1436 1437 <br><dt>‘<samp><span class="samp">fprnd</span></samp>’<dt>‘<samp><span class="samp">no-fprnd</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022fprnd_0022_0029_007d-attribute-2730"></a>Generate code that uses (does not use) the FP round to integer 1438instructions implemented on the POWER5+ processor and other processors 1439that support the PowerPC V2.03 architecture. 1440 1441 <br><dt>‘<samp><span class="samp">hard-dfp</span></samp>’<dt>‘<samp><span class="samp">no-hard-dfp</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022hard_002ddfp_0022_0029_007d-attribute-2731"></a>Generate code that uses (does not use) the decimal floating-point 1442instructions implemented on some POWER processors. 1443 1444 <br><dt>‘<samp><span class="samp">isel</span></samp>’<dt>‘<samp><span class="samp">no-isel</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022isel_0022_0029_007d-attribute-2732"></a>Generate code that uses (does not use) ISEL instruction. 1445 1446 <br><dt>‘<samp><span class="samp">mfcrf</span></samp>’<dt>‘<samp><span class="samp">no-mfcrf</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022mfcrf_0022_0029_007d-attribute-2733"></a>Generate code that uses (does not use) the move from condition 1447register field instruction implemented on the POWER4 processor and 1448other processors that support the PowerPC V2.01 architecture. 1449 1450 <br><dt>‘<samp><span class="samp">mfpgpr</span></samp>’<dt>‘<samp><span class="samp">no-mfpgpr</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022mfpgpr_0022_0029_007d-attribute-2734"></a>Generate code that uses (does not use) the FP move to/from general 1451purpose register instructions implemented on the POWER6X processor and 1452other processors that support the extended PowerPC V2.05 architecture. 1453 1454 <br><dt>‘<samp><span class="samp">mulhw</span></samp>’<dt>‘<samp><span class="samp">no-mulhw</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022mulhw_0022_0029_007d-attribute-2735"></a>Generate code that uses (does not use) the half-word multiply and 1455multiply-accumulate instructions on the IBM 405, 440, 464 and 476 processors. 1456These instructions are generated by default when targeting those 1457processors. 1458 1459 <br><dt>‘<samp><span class="samp">multiple</span></samp>’<dt>‘<samp><span class="samp">no-multiple</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022multiple_0022_0029_007d-attribute-2736"></a>Generate code that uses (does not use) the load multiple word 1460instructions and the store multiple word instructions. 1461 1462 <br><dt>‘<samp><span class="samp">update</span></samp>’<dt>‘<samp><span class="samp">no-update</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022update_0022_0029_007d-attribute-2737"></a>Generate code that uses (does not use) the load or store instructions 1463that update the base register to the address of the calculated memory 1464location. 1465 1466 <br><dt>‘<samp><span class="samp">popcntb</span></samp>’<dt>‘<samp><span class="samp">no-popcntb</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022popcntb_0022_0029_007d-attribute-2738"></a>Generate code that uses (does not use) the popcount and double-precision 1467FP reciprocal estimate instruction implemented on the POWER5 1468processor and other processors that support the PowerPC V2.02 1469architecture. 1470 1471 <br><dt>‘<samp><span class="samp">popcntd</span></samp>’<dt>‘<samp><span class="samp">no-popcntd</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022popcntd_0022_0029_007d-attribute-2739"></a>Generate code that uses (does not use) the popcount instruction 1472implemented on the POWER7 processor and other processors that support 1473the PowerPC V2.06 architecture. 1474 1475 <br><dt>‘<samp><span class="samp">powerpc-gfxopt</span></samp>’<dt>‘<samp><span class="samp">no-powerpc-gfxopt</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022powerpc_002dgfxopt_0022_0029_007d-attribute-2740"></a>Generate code that uses (does not use) the optional PowerPC 1476architecture instructions in the Graphics group, including 1477floating-point select. 1478 1479 <br><dt>‘<samp><span class="samp">powerpc-gpopt</span></samp>’<dt>‘<samp><span class="samp">no-powerpc-gpopt</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022powerpc_002dgpopt_0022_0029_007d-attribute-2741"></a>Generate code that uses (does not use) the optional PowerPC 1480architecture instructions in the General Purpose group, including 1481floating-point square root. 1482 1483 <br><dt>‘<samp><span class="samp">recip-precision</span></samp>’<dt>‘<samp><span class="samp">no-recip-precision</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022recip_002dprecision_0022_0029_007d-attribute-2742"></a>Assume (do not assume) that the reciprocal estimate instructions 1484provide higher-precision estimates than is mandated by the powerpc 1485ABI. 1486 1487 <br><dt>‘<samp><span class="samp">string</span></samp>’<dt>‘<samp><span class="samp">no-string</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022string_0022_0029_007d-attribute-2743"></a>Generate code that uses (does not use) the load string instructions 1488and the store string word instructions to save multiple registers and 1489do small block moves. 1490 1491 <br><dt>‘<samp><span class="samp">vsx</span></samp>’<dt>‘<samp><span class="samp">no-vsx</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022vsx_0022_0029_007d-attribute-2744"></a>Generate code that uses (does not use) vector/scalar (VSX) 1492instructions, and also enable the use of built-in functions that allow 1493more direct access to the VSX instruction set. In 32-bit code, you 1494cannot enable VSX or AltiVec instructions unless 1495<samp><span class="option">-mabi=altivec</span></samp> is used on the command line. 1496 1497 <br><dt>‘<samp><span class="samp">friz</span></samp>’<dt>‘<samp><span class="samp">no-friz</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022friz_0022_0029_007d-attribute-2745"></a>Generate (do not generate) the <code>friz</code> instruction when the 1498<samp><span class="option">-funsafe-math-optimizations</span></samp> option is used to optimize 1499rounding a floating-point value to 64-bit integer and back to floating 1500point. The <code>friz</code> instruction does not return the same value if 1501the floating-point number is too large to fit in an integer. 1502 1503 <br><dt>‘<samp><span class="samp">avoid-indexed-addresses</span></samp>’<dt>‘<samp><span class="samp">no-avoid-indexed-addresses</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022avoid_002dindexed_002daddresses_0022_0029_007d-attribute-2746"></a>Generate code that tries to avoid (not avoid) the use of indexed load 1504or store instructions. 1505 1506 <br><dt>‘<samp><span class="samp">paired</span></samp>’<dt>‘<samp><span class="samp">no-paired</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022paired_0022_0029_007d-attribute-2747"></a>Generate code that uses (does not use) the generation of PAIRED simd 1507instructions. 1508 1509 <br><dt>‘<samp><span class="samp">longcall</span></samp>’<dt>‘<samp><span class="samp">no-longcall</span></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022longcall_0022_0029_007d-attribute-2748"></a>Generate code that assumes (does not assume) that all calls are far 1510away so that a longer more expensive calling sequence is required. 1511 1512 <br><dt>‘<samp><span class="samp">cpu=</span><var>CPU</var></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022cpu_003d_0040var_007bCPU_007d_0022_0029_007d-attribute-2749"></a>Specify the architecture to generate code for when compiling the 1513function. If you select the <code>target("cpu=power7")</code> attribute when 1514generating 32-bit code, VSX and AltiVec instructions are not generated 1515unless you use the <samp><span class="option">-mabi=altivec</span></samp> option on the command line. 1516 1517 <br><dt>‘<samp><span class="samp">tune=</span><var>TUNE</var></samp>’<dd><a name="index-g_t_0040code_007btarget_0028_0022tune_003d_0040var_007bTUNE_007d_0022_0029_007d-attribute-2750"></a>Specify the architecture to tune for when compiling the function. If 1518you do not specify the <code>target("tune=</code><var>TUNE</var><code>")</code> attribute and 1519you do specify the <code>target("cpu=</code><var>CPU</var><code>")</code> attribute, 1520compilation tunes for the <var>CPU</var> architecture, and not the 1521default tuning specified on the command line. 1522</dl> 1523 1524 <p>On the 386/x86_64 and PowerPC back ends, you can use either multiple 1525strings to specify multiple options, or you can separate the option 1526with a comma (<code>,</code>). 1527 1528 <p>On the 386/x86_64 and PowerPC back ends, the inliner does not inline a 1529function that has different target options than the caller, unless the 1530callee has a subset of the target options of the caller. For example 1531a function declared with <code>target("sse3")</code> can inline a function 1532with <code>target("sse2")</code>, since <code>-msse3</code> implies <code>-msse2</code>. 1533 1534 <p>The <code>target</code> attribute is not implemented in GCC versions earlier 1535than 4.4 for the i386/x86_64 and 4.6 for the PowerPC back ends. It is 1536not currently implemented for other back ends. 1537 1538 <br><dt><code>tiny_data</code><dd><a name="index-tiny-data-section-on-the-H8_002f300H-and-H8S-2751"></a>Use this attribute on the H8/300H and H8S to indicate that the specified 1539variable should be placed into the tiny data section. 1540The compiler generates more efficient code for loads and stores 1541on data in the tiny data section. Note the tiny data area is limited to 1542slightly under 32KB of data. 1543 1544 <br><dt><code>trap_exit</code><dd><a name="index-g_t_0040code_007btrap_005fexit_007d-attribute-2752"></a>Use this attribute on the SH for an <code>interrupt_handler</code> to return using 1545<code>trapa</code> instead of <code>rte</code>. This attribute expects an integer 1546argument specifying the trap number to be used. 1547 1548 <br><dt><code>trapa_handler</code><dd><a name="index-g_t_0040code_007btrapa_005fhandler_007d-attribute-2753"></a>On SH targets this function attribute is similar to <code>interrupt_handler</code> 1549but it does not save and restore all registers. 1550 1551 <br><dt><code>unused</code><dd><a name="index-g_t_0040code_007bunused_007d-attribute_002e-2754"></a>This attribute, attached to a function, means that the function is meant 1552to be possibly unused. GCC does not produce a warning for this 1553function. 1554 1555 <br><dt><code>used</code><dd><a name="index-g_t_0040code_007bused_007d-attribute_002e-2755"></a>This attribute, attached to a function, means that code must be emitted 1556for the function even if it appears that the function is not referenced. 1557This is useful, for example, when the function is referenced only in 1558inline assembly. 1559 1560 <p>When applied to a member function of a C++ class template, the 1561attribute also means that the function is instantiated if the 1562class itself is instantiated. 1563 1564 <br><dt><code>version_id</code><dd><a name="index-g_t_0040code_007bversion_005fid_007d-attribute-2756"></a>This IA-64 HP-UX attribute, attached to a global variable or function, renames a 1565symbol to contain a version string, thus allowing for function level 1566versioning. HP-UX system header files may use version level functioning 1567for some system calls. 1568 1569 <pre class="smallexample"> extern int foo () __attribute__((version_id ("20040821"))); 1570</pre> 1571 <p class="noindent">Calls to <var>foo</var> are mapped to calls to <var>foo{20040821}</var>. 1572 1573 <br><dt><code>visibility ("</code><var>visibility_type</var><code>")</code><dd><a name="index-g_t_0040code_007bvisibility_007d-attribute-2757"></a>This attribute affects the linkage of the declaration to which it is attached. 1574There are four supported <var>visibility_type</var> values: default, 1575hidden, protected or internal visibility. 1576 1577 <pre class="smallexample"> void __attribute__ ((visibility ("protected"))) 1578 f () { /* <span class="roman">Do something.</span> */; } 1579 int i __attribute__ ((visibility ("hidden"))); 1580</pre> 1581 <p>The possible values of <var>visibility_type</var> correspond to the 1582visibility settings in the ELF gABI. 1583 1584 <dl> 1585<!-- keep this list of visibilities in alphabetical order. --> 1586 1587 <dt><dfn>default</dfn><dd>Default visibility is the normal case for the object file format. 1588This value is available for the visibility attribute to override other 1589options that may change the assumed visibility of entities. 1590 1591 <p>On ELF, default visibility means that the declaration is visible to other 1592modules and, in shared libraries, means that the declared entity may be 1593overridden. 1594 1595 <p>On Darwin, default visibility means that the declaration is visible to 1596other modules. 1597 1598 <p>Default visibility corresponds to “external linkage” in the language. 1599 1600 <br><dt><dfn>hidden</dfn><dd>Hidden visibility indicates that the entity declared has a new 1601form of linkage, which we call “hidden linkage”. Two 1602declarations of an object with hidden linkage refer to the same object 1603if they are in the same shared object. 1604 1605 <br><dt><dfn>internal</dfn><dd>Internal visibility is like hidden visibility, but with additional 1606processor specific semantics. Unless otherwise specified by the 1607psABI, GCC defines internal visibility to mean that a function is 1608<em>never</em> called from another module. Compare this with hidden 1609functions which, while they cannot be referenced directly by other 1610modules, can be referenced indirectly via function pointers. By 1611indicating that a function cannot be called from outside the module, 1612GCC may for instance omit the load of a PIC register since it is known 1613that the calling function loaded the correct value. 1614 1615 <br><dt><dfn>protected</dfn><dd>Protected visibility is like default visibility except that it 1616indicates that references within the defining module bind to the 1617definition in that module. That is, the declared entity cannot be 1618overridden by another module. 1619 1620 </dl> 1621 1622 <p>All visibilities are supported on many, but not all, ELF targets 1623(supported when the assembler supports the ‘<samp><span class="samp">.visibility</span></samp>’ 1624pseudo-op). Default visibility is supported everywhere. Hidden 1625visibility is supported on Darwin targets. 1626 1627 <p>The visibility attribute should be applied only to declarations that 1628would otherwise have external linkage. The attribute should be applied 1629consistently, so that the same entity should not be declared with 1630different settings of the attribute. 1631 1632 <p>In C++, the visibility attribute applies to types as well as functions 1633and objects, because in C++ types have linkage. A class must not have 1634greater visibility than its non-static data member types and bases, 1635and class members default to the visibility of their class. Also, a 1636declaration without explicit visibility is limited to the visibility 1637of its type. 1638 1639 <p>In C++, you can mark member functions and static member variables of a 1640class with the visibility attribute. This is useful if you know a 1641particular method or static member variable should only be used from 1642one shared object; then you can mark it hidden while the rest of the 1643class has default visibility. Care must be taken to avoid breaking 1644the One Definition Rule; for example, it is usually not useful to mark 1645an inline method as hidden without marking the whole class as hidden. 1646 1647 <p>A C++ namespace declaration can also have the visibility attribute. 1648This attribute applies only to the particular namespace body, not to 1649other definitions of the same namespace; it is equivalent to using 1650‘<samp><span class="samp">#pragma GCC visibility</span></samp>’ before and after the namespace 1651definition (see <a href="Visibility-Pragmas.html#Visibility-Pragmas">Visibility Pragmas</a>). 1652 1653 <p>In C++, if a template argument has limited visibility, this 1654restriction is implicitly propagated to the template instantiation. 1655Otherwise, template instantiations and specializations default to the 1656visibility of their template. 1657 1658 <p>If both the template and enclosing class have explicit visibility, the 1659visibility from the template is used. 1660 1661 <br><dt><code>vliw</code><dd><a name="index-g_t_0040code_007bvliw_007d-attribute-2758"></a>On MeP, the <code>vliw</code> attribute tells the compiler to emit 1662instructions in VLIW mode instead of core mode. Note that this 1663attribute is not allowed unless a VLIW coprocessor has been configured 1664and enabled through command-line options. 1665 1666 <br><dt><code>warn_unused_result</code><dd><a name="index-g_t_0040code_007bwarn_005funused_005fresult_007d-attribute-2759"></a>The <code>warn_unused_result</code> attribute causes a warning to be emitted 1667if a caller of the function with this attribute does not use its 1668return value. This is useful for functions where not checking 1669the result is either a security problem or always a bug, such as 1670<code>realloc</code>. 1671 1672 <pre class="smallexample"> int fn () __attribute__ ((warn_unused_result)); 1673 int foo () 1674 { 1675 if (fn () < 0) return -1; 1676 fn (); 1677 return 0; 1678 } 1679</pre> 1680 <p class="noindent">results in warning on line 5. 1681 1682 <br><dt><code>weak</code><dd><a name="index-g_t_0040code_007bweak_007d-attribute-2760"></a>The <code>weak</code> attribute causes the declaration to be emitted as a weak 1683symbol rather than a global. This is primarily useful in defining 1684library functions that can be overridden in user code, though it can 1685also be used with non-function declarations. Weak symbols are supported 1686for ELF targets, and also for a.out targets when using the GNU assembler 1687and linker. 1688 1689 <br><dt><code>weakref</code><dt><code>weakref ("</code><var>target</var><code>")</code><dd><a name="index-g_t_0040code_007bweakref_007d-attribute-2761"></a>The <code>weakref</code> attribute marks a declaration as a weak reference. 1690Without arguments, it should be accompanied by an <code>alias</code> attribute 1691naming the target symbol. Optionally, the <var>target</var> may be given as 1692an argument to <code>weakref</code> itself. In either case, <code>weakref</code> 1693implicitly marks the declaration as <code>weak</code>. Without a 1694<var>target</var>, given as an argument to <code>weakref</code> or to <code>alias</code>, 1695<code>weakref</code> is equivalent to <code>weak</code>. 1696 1697 <pre class="smallexample"> static int x() __attribute__ ((weakref ("y"))); 1698 /* is equivalent to... */ 1699 static int x() __attribute__ ((weak, weakref, alias ("y"))); 1700 /* and to... */ 1701 static int x() __attribute__ ((weakref)); 1702 static int x() __attribute__ ((alias ("y"))); 1703</pre> 1704 <p>A weak reference is an alias that does not by itself require a 1705definition to be given for the target symbol. If the target symbol is 1706only referenced through weak references, then it becomes a <code>weak</code> 1707undefined symbol. If it is directly referenced, however, then such 1708strong references prevail, and a definition is required for the 1709symbol, not necessarily in the same translation unit. 1710 1711 <p>The effect is equivalent to moving all references to the alias to a 1712separate translation unit, renaming the alias to the aliased symbol, 1713declaring it as weak, compiling the two separate translation units and 1714performing a reloadable link on them. 1715 1716 <p>At present, a declaration to which <code>weakref</code> is attached can 1717only be <code>static</code>. 1718 1719 </dl> 1720 1721 <p>You can specify multiple attributes in a declaration by separating them 1722by commas within the double parentheses or by immediately following an 1723attribute declaration with another attribute declaration. 1724 1725 <p><a name="index-g_t_0040code_007b_0023pragma_007d_002c-reason-for-not-using-2762"></a><a name="index-pragma_002c-reason-for-not-using-2763"></a>Some people object to the <code>__attribute__</code> feature, suggesting that 1726ISO C's <code>#pragma</code> should be used instead. At the time 1727<code>__attribute__</code> was designed, there were two reasons for not doing 1728this. 1729 1730 <ol type=1 start=1> 1731<li>It is impossible to generate <code>#pragma</code> commands from a macro. 1732 1733 <li>There is no telling what the same <code>#pragma</code> might mean in another 1734compiler. 1735 </ol> 1736 1737 <p>These two reasons applied to almost any application that might have been 1738proposed for <code>#pragma</code>. It was basically a mistake to use 1739<code>#pragma</code> for <em>anything</em>. 1740 1741 <p>The ISO C99 standard includes <code>_Pragma</code>, which now allows pragmas 1742to be generated from macros. In addition, a <code>#pragma GCC</code> 1743namespace is now in use for GCC-specific pragmas. However, it has been 1744found convenient to use <code>__attribute__</code> to achieve a natural 1745attachment of attributes to their corresponding declarations, whereas 1746<code>#pragma GCC</code> is of use for constructs that do not naturally form 1747part of the grammar. See <a href="Pragmas.html#Pragmas">Pragmas Accepted by GCC</a>. 1748 1749 </body></html> 1750 1751