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, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 141998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 152010 Free Software Foundation, Inc. 16 17Permission is granted to copy, distribute and/or modify this document 18under the terms of the GNU Free Documentation License, Version 1.3 or 19any later version published by the Free Software Foundation; with the 20Invariant Sections being ``Funding Free Software'', the Front-Cover 21Texts being (a) (see below), and with the Back-Cover Texts being (b) 22(see below). A copy of the license is included in the section entitled 23``GNU Free Documentation License''. 24 25(a) The FSF's Front-Cover Text is: 26 27 A GNU Manual 28 29(b) The FSF's Back-Cover Text is: 30 31 You have freedom to copy and modify this GNU Manual, like GNU 32 software. Copies published by the Free Software Foundation raise 33 funds for GNU development.--> 34<meta http-equiv="Content-Style-Type" content="text/css"> 35<style type="text/css"><!-- 36 pre.display { font-family:inherit } 37 pre.format { font-family:inherit } 38 pre.smalldisplay { font-family:inherit; font-size:smaller } 39 pre.smallformat { font-family:inherit; font-size:smaller } 40 pre.smallexample { font-size:smaller } 41 pre.smalllisp { font-size:smaller } 42 span.sc { font-variant:small-caps } 43 span.roman { font-family:serif; font-weight:normal; } 44 span.sansserif { font-family:sans-serif; font-weight:normal; } 45--></style> 46<link rel="stylesheet" type="text/css" href="../cs.css"> 47</head> 48<body> 49<div class="node"> 50<a name="Function-Attributes"></a> 51<p> 52Next: <a rel="next" accesskey="n" href="Attribute-Syntax.html#Attribute-Syntax">Attribute Syntax</a>, 53Previous: <a rel="previous" accesskey="p" href="Mixed-Declarations.html#Mixed-Declarations">Mixed Declarations</a>, 54Up: <a rel="up" accesskey="u" href="C-Extensions.html#C-Extensions">C Extensions</a> 55<hr> 56</div> 57 58<h3 class="section">6.30 Declaring Attributes of Functions</h3> 59 60<p><a name="index-function-attributes-2392"></a><a name="index-declaring-attributes-of-functions-2393"></a><a name="index-functions-that-never-return-2394"></a><a name="index-functions-that-return-more-than-once-2395"></a><a name="index-functions-that-have-no-side-effects-2396"></a><a name="index-functions-in-arbitrary-sections-2397"></a><a name="index-functions-that-behave-like-malloc-2398"></a><a name="index-g_t_0040code_007bvolatile_007d-applied-to-function-2399"></a><a name="index-g_t_0040code_007bconst_007d-applied-to-function-2400"></a><a name="index-functions-with-_0040code_007bprintf_007d_002c-_0040code_007bscanf_007d_002c-_0040code_007bstrftime_007d-or-_0040code_007bstrfmon_007d-style-arguments-2401"></a><a name="index-functions-with-non_002dnull-pointer-arguments-2402"></a><a name="index-functions-that-are-passed-arguments-in-registers-on-the-386-2403"></a><a name="index-functions-that-pop-the-argument-stack-on-the-386-2404"></a><a name="index-functions-that-do-not-pop-the-argument-stack-on-the-386-2405"></a><a name="index-functions-that-have-different-compilation-options-on-the-386-2406"></a><a name="index-functions-that-have-different-optimization-options-2407"></a><a name="index-functions-that-are-dynamically-resolved-2408"></a> 61In GNU C, you declare certain things about functions called in your program 62which help the compiler optimize function calls and check your code more 63carefully. 64 65 <p>The keyword <code>__attribute__</code> allows you to specify special 66attributes when making a declaration. This keyword is followed by an 67attribute specification inside double parentheses. The following 68attributes are currently defined for functions on all targets: 69<code>aligned</code>, <code>alloc_size</code>, <code>noreturn</code>, 70<code>returns_twice</code>, <code>noinline</code>, <code>noclone</code>, 71<code>always_inline</code>, <code>flatten</code>, <code>pure</code>, <code>const</code>, 72<code>nothrow</code>, <code>sentinel</code>, <code>format</code>, <code>format_arg</code>, 73<code>no_instrument_function</code>, <code>no_split_stack</code>, 74<code>section</code>, <code>constructor</code>, 75<code>destructor</code>, <code>used</code>, <code>unused</code>, <code>deprecated</code>, 76<code>weak</code>, <code>malloc</code>, <code>alias</code>, <code>ifunc</code>, 77<code>warn_unused_result</code>, <code>nonnull</code>, <code>gnu_inline</code>, 78<code>externally_visible</code>, <code>hot</code>, <code>cold</code>, <code>artificial</code>, 79<code>error</code> and <code>warning</code>. Several other attributes are defined 80for functions on particular target systems. Other attributes, 81including <code>section</code> are supported for variables declarations 82(see <a href="Variable-Attributes.html#Variable-Attributes">Variable Attributes</a>) and 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-2409"></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>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-2410"></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 will override 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-2411"></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>declares that my_calloc will return memory of the size given by 145the product of parameter 1 and 2 and that my_realloc will return 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-2412"></a>Generally, functions are not inlined unless optimization is specified. 149For functions declared inline, this attribute inlines the function even 150if no optimization level was specified. 151 152 <br><dt><code>gnu_inline</code><dd><a name="index-g_t_0040code_007bgnu_005finline_007d-function-attribute-2413"></a>This attribute should be used with a function which 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 will cause most calls to the 166function to be inlined. If any uses of the function remain, they will 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-2414"></a>This attribute is useful for small inline wrappers which if possible 188should appear during debugging as a unit, depending on the debug 189info format it will either mean 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-2415"></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-2416"></a>Generally, inlining into a function is limited. For a function marked with 198this attribute, every call inside this function will be 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-2417"></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 204which will include <var>message</var> will be 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 will be 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-2418"></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 215which will include <var>message</var> will be 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 219will be 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-2419"></a><a name="index-mrtd-2420"></a>On the Intel 386, the <code>cdecl</code> attribute causes the compiler to 223assume that the calling function will pop 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-2421"></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-2422"></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>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-2423"></a><a name="index-g_t_0040code_007bdestructor_007d-function-attribute-2424"></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> has completed or <code>exit ()</code> has 254been called. Functions with these attributes are useful for 255initializing data that will be 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-2425"></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>results in a warning on line 3 but not line 2. The optional msg 283argument, which must be a string, will be 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-2426"></a>On 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-2427"></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 behaviour now is to emit all dllexported 311inline functions; however, this can cause object file-size bloat, in 312which case the old behaviour 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-2428"></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 357dllimport'ed 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 based 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-bit-data-on-the-H8_002f300_002c-H8_002f300H_002c-and-H8S-2429"></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 will generate 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-2430"></a>Use this attribute on the Blackfin to indicate that the specified function 389is an exception handler. The compiler will generate 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-2431"></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. If <samp><span class="option">-fwhole-program</span></samp> is used together with <samp><span class="option">-flto</span></samp> and <samp><span class="command">gold</span></samp> is used as the linker plugin, <code>externally_visible</code> attributes are automatically added to functions (not variable yet due to a current <samp><span class="command">gold</span></samp> issue) that are accessed outside of LTO objects according to resolution file produced by <samp><span class="command">gold</span></samp>. For other linkers that cannot generate resolution file, explicit <code>externally_visible</code> attributes are still necessary. 396 397 <br><dt><code>far</code><dd><a name="index-functions-which-handle-memory-bank-switching-2432"></a>On 68HC11 and 68HC12 the <code>far</code> attribute causes the compiler to 398use a calling convention that takes care of switching memory banks when 399entering and leaving a function. This calling convention is also the 400default when using the <samp><span class="option">-mlong-calls</span></samp> option. 401 402 <p>On 68HC12 the compiler will use the <code>call</code> and <code>rtc</code> instructions 403to call and return from a function. 404 405 <p>On 68HC11 the compiler will generate a sequence of instructions 406to invoke a board-specific routine to switch the memory bank and call the 407real function. The board-specific routine simulates a <code>call</code>. 408At the end of a function, it will jump to a board-specific routine 409instead of using <code>rts</code>. The board-specific return routine simulates 410the <code>rtc</code>. 411 412 <p>On MeP targets this causes the compiler to use a calling convention 413which assumes the called function is too far away for the built-in 414addressing modes. 415 416 <br><dt><code>fast_interrupt</code><dd><a name="index-interrupt-handler-functions-2433"></a>Use this attribute on the M32C and RX ports to indicate that the specified 417function is a fast interrupt handler. This is just like the 418<code>interrupt</code> attribute, except that <code>freit</code> is used to return 419instead of <code>reit</code>. 420 421 <br><dt><code>fastcall</code><dd><a name="index-functions-that-pop-the-argument-stack-on-the-386-2434"></a>On the Intel 386, the <code>fastcall</code> attribute causes the compiler to 422pass the first argument (if of integral type) in the register ECX and 423the second argument (if of integral type) in the register EDX. Subsequent 424and other typed arguments are passed on the stack. The called function will 425pop the arguments off the stack. If the number of arguments is variable all 426arguments are pushed on the stack. 427 428 <br><dt><code>thiscall</code><dd><a name="index-functions-that-pop-the-argument-stack-on-the-386-2435"></a>On the Intel 386, the <code>thiscall</code> attribute causes the compiler to 429pass the first argument (if of integral type) in the register ECX. 430Subsequent and other typed arguments are passed on the stack. The called 431function will pop the arguments off the stack. 432If the number of arguments is variable all arguments are pushed on the 433stack. 434The <code>thiscall</code> attribute is intended for C++ non-static member functions. 435As gcc extension this calling convention can be used for C-functions 436and for static member methods. 437 438 <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-2436"></a><a name="index-Wformat-2437"></a>The <code>format</code> attribute specifies that a function takes <code>printf</code>, 439<code>scanf</code>, <code>strftime</code> or <code>strfmon</code> style arguments which 440should be type-checked against a format string. For example, the 441declaration: 442 443 <pre class="smallexample"> extern int 444 my_printf (void *my_object, const char *my_format, ...) 445 __attribute__ ((format (printf, 2, 3))); 446</pre> 447 <p class="noindent">causes the compiler to check the arguments in calls to <code>my_printf</code> 448for consistency with the <code>printf</code> style format string argument 449<code>my_format</code>. 450 451 <p>The parameter <var>archetype</var> determines how the format string is 452interpreted, and should be <code>printf</code>, <code>scanf</code>, <code>strftime</code>, 453<code>gnu_printf</code>, <code>gnu_scanf</code>, <code>gnu_strftime</code> or 454<code>strfmon</code>. (You can also use <code>__printf__</code>, 455<code>__scanf__</code>, <code>__strftime__</code> or <code>__strfmon__</code>.) On 456MinGW targets, <code>ms_printf</code>, <code>ms_scanf</code>, and 457<code>ms_strftime</code> are also present. 458<var>archtype</var> values such as <code>printf</code> refer to the formats accepted 459by the system's C run-time library, while <code>gnu_</code> values always refer 460to the formats accepted by the GNU C Library. On Microsoft Windows 461targets, <code>ms_</code> values refer to the formats accepted by the 462<samp><span class="file">msvcrt.dll</span></samp> library. 463The parameter <var>string-index</var> 464specifies which argument is the format string argument (starting 465from 1), while <var>first-to-check</var> is the number of the first 466argument to check against the format string. For functions 467where the arguments are not available to be checked (such as 468<code>vprintf</code>), specify the third parameter as zero. In this case the 469compiler only checks the format string for consistency. For 470<code>strftime</code> formats, the third parameter is required to be zero. 471Since non-static C++ methods have an implicit <code>this</code> argument, the 472arguments of such methods should be counted from two, not one, when 473giving values for <var>string-index</var> and <var>first-to-check</var>. 474 475 <p>In the example above, the format string (<code>my_format</code>) is the second 476argument of the function <code>my_print</code>, and the arguments to check 477start with the third argument, so the correct parameters for the format 478attribute are 2 and 3. 479 480 <p><a name="index-ffreestanding-2438"></a><a name="index-fno_002dbuiltin-2439"></a>The <code>format</code> attribute allows you to identify your own functions 481which take format strings as arguments, so that GCC can check the 482calls to these functions for errors. The compiler always (unless 483<samp><span class="option">-ffreestanding</span></samp> or <samp><span class="option">-fno-builtin</span></samp> is used) checks formats 484for the standard library functions <code>printf</code>, <code>fprintf</code>, 485<code>sprintf</code>, <code>scanf</code>, <code>fscanf</code>, <code>sscanf</code>, <code>strftime</code>, 486<code>vprintf</code>, <code>vfprintf</code> and <code>vsprintf</code> whenever such 487warnings are requested (using <samp><span class="option">-Wformat</span></samp>), so there is no need to 488modify the header file <samp><span class="file">stdio.h</span></samp>. In C99 mode, the functions 489<code>snprintf</code>, <code>vsnprintf</code>, <code>vscanf</code>, <code>vfscanf</code> and 490<code>vsscanf</code> are also checked. Except in strictly conforming C 491standard modes, the X/Open function <code>strfmon</code> is also checked as 492are <code>printf_unlocked</code> and <code>fprintf_unlocked</code>. 493See <a href="C-Dialect-Options.html#C-Dialect-Options">Options Controlling C Dialect</a>. 494 495 <p>For Objective-C dialects, <code>NSString</code> (or <code>__NSString__</code>) is 496recognized in the same context. Declarations including these format attributes 497will be parsed for correct syntax, however the result of checking of such format 498strings is not yet defined, and will not be carried out by this version of the 499compiler. 500 501 <p>The target may also provide additional types of format checks. 502See <a href="Target-Format-Checks.html#Target-Format-Checks">Format Checks Specific to Particular Target Machines</a>. 503 504 <br><dt><code>format_arg (</code><var>string-index</var><code>)</code><dd><a name="index-g_t_0040code_007bformat_005farg_007d-function-attribute-2440"></a><a name="index-Wformat_002dnonliteral-2441"></a>The <code>format_arg</code> attribute specifies that a function takes a format 505string for a <code>printf</code>, <code>scanf</code>, <code>strftime</code> or 506<code>strfmon</code> style function and modifies it (for example, to translate 507it into another language), so the result can be passed to a 508<code>printf</code>, <code>scanf</code>, <code>strftime</code> or <code>strfmon</code> style 509function (with the remaining arguments to the format function the same 510as they would have been for the unmodified string). For example, the 511declaration: 512 513 <pre class="smallexample"> extern char * 514 my_dgettext (char *my_domain, const char *my_format) 515 __attribute__ ((format_arg (2))); 516</pre> 517 <p class="noindent">causes the compiler to check the arguments in calls to a <code>printf</code>, 518<code>scanf</code>, <code>strftime</code> or <code>strfmon</code> type function, whose 519format string argument is a call to the <code>my_dgettext</code> function, for 520consistency with the format string argument <code>my_format</code>. If the 521<code>format_arg</code> attribute had not been specified, all the compiler 522could tell in such calls to format functions would be that the format 523string argument is not constant; this would generate a warning when 524<samp><span class="option">-Wformat-nonliteral</span></samp> is used, but the calls could not be checked 525without the attribute. 526 527 <p>The parameter <var>string-index</var> specifies which argument is the format 528string argument (starting from one). Since non-static C++ methods have 529an implicit <code>this</code> argument, the arguments of such methods should 530be counted from two. 531 532 <p>The <code>format-arg</code> attribute allows you to identify your own 533functions which modify format strings, so that GCC can check the 534calls to <code>printf</code>, <code>scanf</code>, <code>strftime</code> or <code>strfmon</code> 535type function whose operands are a call to one of your own function. 536The compiler always treats <code>gettext</code>, <code>dgettext</code>, and 537<code>dcgettext</code> in this manner except when strict ISO C support is 538requested by <samp><span class="option">-ansi</span></samp> or an appropriate <samp><span class="option">-std</span></samp> option, or 539<samp><span class="option">-ffreestanding</span></samp> or <samp><span class="option">-fno-builtin</span></samp> 540is used. See <a href="C-Dialect-Options.html#C-Dialect-Options">Options Controlling C Dialect</a>. 541 542 <p>For Objective-C dialects, the <code>format-arg</code> attribute may refer to an 543<code>NSString</code> reference for compatibility with the <code>format</code> attribute 544above. 545 546 <p>The target may also allow additional types in <code>format-arg</code> attributes. 547See <a href="Target-Format-Checks.html#Target-Format-Checks">Format Checks Specific to Particular Target Machines</a>. 548 549 <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-2442"></a>Use this attribute on the H8/300, H8/300H, and H8S to indicate that the specified 550function should be called through the function vector. Calling a 551function through the function vector will reduce code size, however; 552the function vector has a limited size (maximum 128 entries on the H8/300 553and 64 entries on the H8/300H and H8S) and shares space with the interrupt vector. 554 555 <p>In SH2A target, this attribute declares a function to be called using the 556TBR relative addressing mode. The argument to this attribute is the entry 557number of the same function in a vector table containing all the TBR 558relative addressable functions. For the successful jump, register TBR 559should contain the start address of this TBR relative vector table. 560In the startup routine of the user application, user needs to care of this 561TBR register initialization. The TBR relative vector table can have at 562max 256 function entries. The jumps to these functions will be generated 563using a SH2A specific, non delayed branch instruction JSR/N @(disp8,TBR). 564You must use GAS and GLD from GNU binutils version 2.7 or later for 565this attribute to work correctly. 566 567 <p>Please refer the example of M16C target, to see the use of this 568attribute while declaring a function, 569 570 <p>In an application, for a function being called once, this attribute will 571save at least 8 bytes of code; and if other successive calls are being 572made to the same function, it will save 2 bytes of code per each of these 573calls. 574 575 <p>On M16C/M32C targets, the <code>function_vector</code> attribute declares a 576special page subroutine call function. Use of this attribute reduces 577the code size by 2 bytes for each call generated to the 578subroutine. The argument to the attribute is the vector number entry 579from the special page vector table which contains the 16 low-order 580bits of the subroutine's entry address. Each vector table has special 581page number (18 to 255) which are used in <code>jsrs</code> instruction. 582Jump addresses of the routines are generated by adding 0x0F0000 (in 583case of M16C targets) or 0xFF0000 (in case of M32C targets), to the 2 584byte addresses set in the vector table. Therefore you need to ensure 585that all the special page vector routines should get mapped within the 586address range 0x0F0000 to 0x0FFFFF (for M16C) and 0xFF0000 to 0xFFFFFF 587(for M32C). 588 589 <p>In the following example 2 bytes will be saved for each call to 590function <code>foo</code>. 591 592 <pre class="smallexample"> void foo (void) __attribute__((function_vector(0x18))); 593 void foo (void) 594 { 595 } 596 597 void bar (void) 598 { 599 foo(); 600 } 601</pre> 602 <p>If functions are defined in one file and are called in another file, 603then be sure to write this declaration in both files. 604 605 <p>This attribute is ignored for R8C target. 606 607 <br><dt><code>interrupt</code><dd><a name="index-interrupt-handler-functions-2443"></a>Use this attribute on the ARM, AVR, CRX, M32C, M32R/D, m68k, MeP, MIPS, 608RX and Xstormy16 ports to indicate that the specified function is an 609interrupt handler. The compiler will generate function entry and exit 610sequences suitable for use in an interrupt handler when this attribute 611is present. 612 613 <p>Note, interrupt handlers for the Blackfin, H8/300, H8/300H, H8S, MicroBlaze, 614and SH processors can be specified via the <code>interrupt_handler</code> attribute. 615 616 <p>Note, on the AVR, interrupts will be enabled inside the function. 617 618 <p>Note, for the ARM, you can specify the kind of interrupt to be handled by 619adding an optional parameter to the interrupt attribute like this: 620 621 <pre class="smallexample"> void f () __attribute__ ((interrupt ("IRQ"))); 622</pre> 623 <p>Permissible values for this parameter are: IRQ, FIQ, SWI, ABORT and UNDEF. 624 625 <p>On ARMv7-M the interrupt type is ignored, and the attribute means the function 626may be called with a word aligned stack pointer. 627 628 <p>On MIPS targets, you can use the following attributes to modify the behavior 629of an interrupt handler: 630 <dl> 631<dt><code>use_shadow_register_set</code><dd><a name="index-g_t_0040code_007buse_005fshadow_005fregister_005fset_007d-attribute-2444"></a>Assume that the handler uses a shadow register set, instead of 632the main general-purpose registers. 633 634 <br><dt><code>keep_interrupts_masked</code><dd><a name="index-g_t_0040code_007bkeep_005finterrupts_005fmasked_007d-attribute-2445"></a>Keep interrupts masked for the whole function. Without this attribute, 635GCC tries to reenable interrupts for as much of the function as it can. 636 637 <br><dt><code>use_debug_exception_return</code><dd><a name="index-g_t_0040code_007buse_005fdebug_005fexception_005freturn_007d-attribute-2446"></a>Return using the <code>deret</code> instruction. Interrupt handlers that don't 638have this attribute return using <code>eret</code> instead. 639</dl> 640 641 <p>You can use any combination of these attributes, as shown below: 642 <pre class="smallexample"> void __attribute__ ((interrupt)) v0 (); 643 void __attribute__ ((interrupt, use_shadow_register_set)) v1 (); 644 void __attribute__ ((interrupt, keep_interrupts_masked)) v2 (); 645 void __attribute__ ((interrupt, use_debug_exception_return)) v3 (); 646 void __attribute__ ((interrupt, use_shadow_register_set, 647 keep_interrupts_masked)) v4 (); 648 void __attribute__ ((interrupt, use_shadow_register_set, 649 use_debug_exception_return)) v5 (); 650 void __attribute__ ((interrupt, keep_interrupts_masked, 651 use_debug_exception_return)) v6 (); 652 void __attribute__ ((interrupt, use_shadow_register_set, 653 keep_interrupts_masked, 654 use_debug_exception_return)) v7 (); 655</pre> 656 <br><dt><code>ifunc ("</code><var>resolver</var><code>")</code><dd><a name="index-g_t_0040code_007bifunc_007d-attribute-2447"></a>The <code>ifunc</code> attribute is used to mark a function as an indirect 657function using the STT_GNU_IFUNC symbol type extension to the ELF 658standard. This allows the resolution of the symbol value to be 659determined dynamically at load time, and an optimized version of the 660routine can be selected for the particular processor or other system 661characteristics determined then. To use this attribute, first define 662the implementation functions available, and a resolver function that 663returns a pointer to the selected implementation function. The 664implementation functions' declarations must match the API of the 665function being implemented, the resolver's declaration is be a 666function returning pointer to void function returning void: 667 668 <pre class="smallexample"> void *my_memcpy (void *dst, const void *src, size_t len) 669 { 670 ... 671 } 672 673 static void (*resolve_memcpy (void)) (void) 674 { 675 return my_memcpy; // we'll just always select this routine 676 } 677</pre> 678 <p>The exported header file declaring the function the user calls would 679contain: 680 681 <pre class="smallexample"> extern void *memcpy (void *, const void *, size_t); 682</pre> 683 <p>allowing the user to call this as a regular function, unaware of the 684implementation. Finally, the indirect function needs to be defined in 685the same translation unit as the resolver function: 686 687 <pre class="smallexample"> void *memcpy (void *, const void *, size_t) 688 __attribute__ ((ifunc ("resolve_memcpy"))); 689</pre> 690 <p>Indirect functions cannot be weak, and require a recent binutils (at 691least version 2.20.1), and GNU C library (at least version 2.11.1). 692 693 <br><dt><code>interrupt_handler</code><dd><a name="index-interrupt-handler-functions-on-the-Blackfin_002c-m68k_002c-H8_002f300-and-SH-processors-2448"></a>Use this attribute on the Blackfin, m68k, H8/300, H8/300H, H8S, and SH to 694indicate that the specified function is an interrupt handler. The compiler 695will generate function entry and exit sequences suitable for use in an 696interrupt handler when this attribute is present. 697 698 <br><dt><code>interrupt_thread</code><dd><a name="index-interrupt-thread-functions-on-fido-2449"></a>Use this attribute on fido, a subarchitecture of the m68k, to indicate 699that the specified function is an interrupt handler that is designed 700to run as a thread. The compiler omits generate prologue/epilogue 701sequences and replaces the return instruction with a <code>sleep</code> 702instruction. This attribute is available only on fido. 703 704 <br><dt><code>isr</code><dd><a name="index-interrupt-service-routines-on-ARM-2450"></a>Use this attribute on ARM to write Interrupt Service Routines. This is an 705alias to the <code>interrupt</code> attribute above. 706 707 <br><dt><code>kspisusp</code><dd><a name="index-User-stack-pointer-in-interrupts-on-the-Blackfin-2451"></a>When used together with <code>interrupt_handler</code>, <code>exception_handler</code> 708or <code>nmi_handler</code>, code will be generated to load the stack pointer 709from the USP register in the function prologue. 710 711 <br><dt><code>l1_text</code><dd><a name="index-g_t_0040code_007bl1_005ftext_007d-function-attribute-2452"></a>This attribute specifies a function to be placed into L1 Instruction 712SRAM. The function will be put into a specific section named <code>.l1.text</code>. 713With <samp><span class="option">-mfdpic</span></samp>, function calls with a such function as the callee 714or caller will use inlined PLT. 715 716 <br><dt><code>l2</code><dd><a name="index-g_t_0040code_007bl2_007d-function-attribute-2453"></a>On the Blackfin, this attribute specifies a function to be placed into L2 717SRAM. The function will be put into a specific section named 718<code>.l1.text</code>. With <samp><span class="option">-mfdpic</span></samp>, callers of such functions will use 719an inlined PLT. 720 721 <br><dt><code>leaf</code><dd><a name="index-g_t_0040code_007bleaf_007d-function-attribute-2454"></a>Calls to external functions with this attribute must return to the current 722compilation unit only by return or by exception handling. In particular, leaf 723functions are not allowed to call callback function passed to it from the current 724compilation unit or directly call functions exported by the unit or longjmp 725into the unit. Leaf function might still call functions from other compilation 726units and thus they are not necessarily leaf in the sense that they contain no 727function calls at all. 728 729 <p>The attribute is intended for library functions to improve dataflow analysis. 730The compiler takes the hint that any data not escaping the current compilation unit can 731not be used or modified by the leaf function. For example, the <code>sin</code> function 732is a leaf function, but <code>qsort</code> is not. 733 734 <p>Note that leaf functions might invoke signals and signal handlers might be 735defined in the current compilation unit and use static variables. The only 736compliant way to write such a signal handler is to declare such variables 737<code>volatile</code>. 738 739 <p>The attribute has no effect on functions defined within the current compilation 740unit. This is to allow easy merging of multiple compilation units into one, 741for example, by using the link time optimization. For this reason the 742attribute is not allowed on types to annotate indirect calls. 743 744 <br><dt><code>long_call/short_call</code><dd><a name="index-indirect-calls-on-ARM-2455"></a>This attribute specifies how a particular function is called on 745ARM. Both attributes override the <samp><span class="option">-mlong-calls</span></samp> (see <a href="ARM-Options.html#ARM-Options">ARM Options</a>) 746command-line switch and <code>#pragma long_calls</code> settings. The 747<code>long_call</code> attribute indicates that the function might be far 748away from the call site and require a different (more expensive) 749calling sequence. The <code>short_call</code> attribute always places 750the offset to the function from the call site into the ‘<samp><span class="samp">BL</span></samp>’ 751instruction directly. 752 753 <br><dt><code>longcall/shortcall</code><dd><a name="index-functions-called-via-pointer-on-the-RS_002f6000-and-PowerPC-2456"></a>On the Blackfin, RS/6000 and PowerPC, the <code>longcall</code> attribute 754indicates that the function might be far away from the call site and 755require a different (more expensive) calling sequence. The 756<code>shortcall</code> attribute indicates that the function is always close 757enough for the shorter calling sequence to be used. These attributes 758override both the <samp><span class="option">-mlongcall</span></samp> switch and, on the RS/6000 and 759PowerPC, the <code>#pragma longcall</code> setting. 760 761 <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 762calls are necessary. 763 764 <br><dt><code>long_call/near/far</code><dd><a name="index-indirect-calls-on-MIPS-2457"></a>These attributes specify how a particular function is called on MIPS. 765The attributes override the <samp><span class="option">-mlong-calls</span></samp> (see <a href="MIPS-Options.html#MIPS-Options">MIPS Options</a>) 766command-line switch. The <code>long_call</code> and <code>far</code> attributes are 767synonyms, and cause the compiler to always call 768the function by first loading its address into a register, and then using 769the contents of that register. The <code>near</code> attribute has the opposite 770effect; it specifies that non-PIC calls should be made using the more 771efficient <code>jal</code> instruction. 772 773 <br><dt><code>malloc</code><dd><a name="index-g_t_0040code_007bmalloc_007d-attribute-2458"></a>The <code>malloc</code> attribute is used to tell the compiler that a function 774may be treated as if any non-<code>NULL</code> pointer it returns cannot 775alias any other pointer valid when the function returns. 776This will often improve optimization. 777Standard functions with this property include <code>malloc</code> and 778<code>calloc</code>. <code>realloc</code>-like functions have this property as 779long as the old pointer is never referred to (including comparing it 780to the new pointer) after the function returns a non-<code>NULL</code> 781value. 782 783 <br><dt><code>mips16/nomips16</code><dd><a name="index-g_t_0040code_007bmips16_007d-attribute-2459"></a><a name="index-g_t_0040code_007bnomips16_007d-attribute-2460"></a> 784On MIPS targets, you can use the <code>mips16</code> and <code>nomips16</code> 785function attributes to locally select or turn off MIPS16 code generation. 786A function with the <code>mips16</code> attribute is emitted as MIPS16 code, 787while MIPS16 code generation is disabled for functions with the 788<code>nomips16</code> attribute. These attributes override the 789<samp><span class="option">-mips16</span></samp> and <samp><span class="option">-mno-mips16</span></samp> options on the command line 790(see <a href="MIPS-Options.html#MIPS-Options">MIPS Options</a>). 791 792 <p>When compiling files containing mixed MIPS16 and non-MIPS16 code, the 793preprocessor symbol <code>__mips16</code> reflects the setting on the command line, 794not that within individual functions. Mixed MIPS16 and non-MIPS16 code 795may interact badly with some GCC extensions such as <code>__builtin_apply</code> 796(see <a href="Constructing-Calls.html#Constructing-Calls">Constructing Calls</a>). 797 798 <br><dt><code>model (</code><var>model-name</var><code>)</code><dd><a name="index-function-addressability-on-the-M32R_002fD-2461"></a><a name="index-variable-addressability-on-the-IA_002d64-2462"></a> 799On the M32R/D, use this attribute to set the addressability of an 800object, and of the code generated for a function. The identifier 801<var>model-name</var> is one of <code>small</code>, <code>medium</code>, or 802<code>large</code>, representing each of the code models. 803 804 <p>Small model objects live in the lower 16MB of memory (so that their 805addresses can be loaded with the <code>ld24</code> instruction), and are 806callable with the <code>bl</code> instruction. 807 808 <p>Medium model objects may live anywhere in the 32-bit address space (the 809compiler will generate <code>seth/add3</code> instructions to load their addresses), 810and are callable with the <code>bl</code> instruction. 811 812 <p>Large model objects may live anywhere in the 32-bit address space (the 813compiler will generate <code>seth/add3</code> instructions to load their addresses), 814and may not be reachable with the <code>bl</code> instruction (the compiler will 815generate the much slower <code>seth/add3/jl</code> instruction sequence). 816 817 <p>On IA-64, use this attribute to set the addressability of an object. 818At present, the only supported identifier for <var>model-name</var> is 819<code>small</code>, indicating addressability via “small” (22-bit) 820addresses (so that their addresses can be loaded with the <code>addl</code> 821instruction). Caveat: such addressing is by definition not position 822independent and hence this attribute must not be used for objects 823defined by shared libraries. 824 825 <br><dt><code>ms_abi/sysv_abi</code><dd><a name="index-g_t_0040code_007bms_005fabi_007d-attribute-2463"></a><a name="index-g_t_0040code_007bsysv_005fabi_007d-attribute-2464"></a> 826On 64-bit x86_64-*-* targets, you can use an ABI attribute to indicate 827which calling convention should be used for a function. The <code>ms_abi</code> 828attribute tells the compiler to use the Microsoft ABI, while the 829<code>sysv_abi</code> attribute tells the compiler to use the ABI used on 830GNU/Linux and other systems. The default is to use the Microsoft ABI 831when targeting Windows. On all other systems, the default is the AMD ABI. 832 833 <p>Note, the <code>ms_abi</code> attribute for Windows targets currently requires 834the <samp><span class="option">-maccumulate-outgoing-args</span></samp> option. 835 836 <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-2465"></a> 837On 32-bit i?86-*-* targets, you can control by those attribute for 838aggregate return in memory, if the caller is responsible to pop the hidden 839pointer together with the rest of the arguments - <var>number</var> equal to 840zero -, or if the callee is responsible to pop hidden pointer - <var>number</var> 841equal to one. 842 843 <p>For i?86-netware, the caller pops the stack for the hidden arguments pointing 844to aggregate return value. This differs from the default i386 ABI which assumes 845that the callee pops the stack for hidden pointer. 846 847 <br><dt><code>ms_hook_prologue</code><dd><a name="index-g_t_0040code_007bms_005fhook_005fprologue_007d-attribute-2466"></a> 848On 32 bit i[34567]86-*-* targets and 64 bit x86_64-*-* targets, you can use 849this function attribute to make gcc generate the "hot-patching" function 850prologue used in Win32 API functions in Microsoft Windows XP Service Pack 2 851and newer. 852 853 <br><dt><code>naked</code><dd><a name="index-function-without-a-prologue_002fepilogue-code-2467"></a>Use this attribute on the ARM, AVR, MCORE, RX and SPU ports to indicate that 854the specified function does not need prologue/epilogue sequences generated by 855the compiler. It is up to the programmer to provide these sequences. The 856only statements that can be safely included in naked functions are 857<code>asm</code> statements that do not have operands. All other statements, 858including declarations of local variables, <code>if</code> statements, and so 859forth, should be avoided. Naked functions should be used to implement the 860body of an assembly function, while allowing the compiler to construct 861the requisite function declaration for the assembler. 862 863 <br><dt><code>near</code><dd><a name="index-functions-which-do-not-handle-memory-bank-switching-on-68HC11_002f68HC12-2468"></a>On 68HC11 and 68HC12 the <code>near</code> attribute causes the compiler to 864use the normal calling convention based on <code>jsr</code> and <code>rts</code>. 865This attribute can be used to cancel the effect of the <samp><span class="option">-mlong-calls</span></samp> 866option. 867 868 <p>On MeP targets this attribute causes the compiler to assume the called 869function is close enough to use the normal calling convention, 870overriding the <code>-mtf</code> command line option. 871 872 <br><dt><code>nesting</code><dd><a name="index-Allow-nesting-in-an-interrupt-handler-on-the-Blackfin-processor_002e-2469"></a>Use this attribute together with <code>interrupt_handler</code>, 873<code>exception_handler</code> or <code>nmi_handler</code> to indicate that the function 874entry code should enable nested interrupts or exceptions. 875 876 <br><dt><code>nmi_handler</code><dd><a name="index-NMI-handler-functions-on-the-Blackfin-processor-2470"></a>Use this attribute on the Blackfin to indicate that the specified function 877is an NMI handler. The compiler will generate function entry and 878exit sequences suitable for use in an NMI handler when this 879attribute is present. 880 881 <br><dt><code>no_instrument_function</code><dd><a name="index-g_t_0040code_007bno_005finstrument_005ffunction_007d-function-attribute-2471"></a><a name="index-finstrument_002dfunctions-2472"></a>If <samp><span class="option">-finstrument-functions</span></samp> is given, profiling function calls will 882be generated at entry and exit of most user-compiled functions. 883Functions with this attribute will not be so instrumented. 884 885 <br><dt><code>no_split_stack</code><dd><a name="index-g_t_0040code_007bno_005fsplit_005fstack_007d-function-attribute-2473"></a><a name="index-fsplit_002dstack-2474"></a>If <samp><span class="option">-fsplit-stack</span></samp> is given, functions will have a small 886prologue which decides whether to split the stack. Functions with the 887<code>no_split_stack</code> attribute will not have that prologue, and thus 888may run with only a small amount of stack space available. 889 890 <br><dt><code>noinline</code><dd><a name="index-g_t_0040code_007bnoinline_007d-function-attribute-2475"></a>This function attribute prevents a function from being considered for 891inlining. 892<!-- Don't enumerate the optimizations by name here; we try to be --> 893<!-- future-compatible with this mechanism. --> 894If the function does not have side-effects, there are optimizations 895other than inlining that causes function calls to be optimized away, 896although the function call is live. To keep such calls from being 897optimized away, put 898 <pre class="smallexample"> asm (""); 899</pre> 900 <p>(see <a href="Extended-Asm.html#Extended-Asm">Extended Asm</a>) in the called function, to serve as a special 901side-effect. 902 903 <br><dt><code>noclone</code><dd><a name="index-g_t_0040code_007bnoclone_007d-function-attribute-2476"></a>This function attribute prevents a function from being considered for 904cloning - a mechanism which produces specialized copies of functions 905and which is (currently) performed by interprocedural constant 906propagation. 907 908 <br><dt><code>nonnull (</code><var>arg-index</var><code>, ...)</code><dd><a name="index-g_t_0040code_007bnonnull_007d-function-attribute-2477"></a>The <code>nonnull</code> attribute specifies that some function parameters should 909be non-null pointers. For instance, the declaration: 910 911 <pre class="smallexample"> extern void * 912 my_memcpy (void *dest, const void *src, size_t len) 913 __attribute__((nonnull (1, 2))); 914</pre> 915 <p class="noindent">causes the compiler to check that, in calls to <code>my_memcpy</code>, 916arguments <var>dest</var> and <var>src</var> are non-null. If the compiler 917determines that a null pointer is passed in an argument slot marked 918as non-null, and the <samp><span class="option">-Wnonnull</span></samp> option is enabled, a warning 919is issued. The compiler may also choose to make optimizations based 920on the knowledge that certain function arguments will not be null. 921 922 <p>If no argument index list is given to the <code>nonnull</code> attribute, 923all pointer arguments are marked as non-null. To illustrate, the 924following declaration is equivalent to the previous example: 925 926 <pre class="smallexample"> extern void * 927 my_memcpy (void *dest, const void *src, size_t len) 928 __attribute__((nonnull)); 929</pre> 930 <br><dt><code>noreturn</code><dd><a name="index-g_t_0040code_007bnoreturn_007d-function-attribute-2478"></a>A few standard library functions, such as <code>abort</code> and <code>exit</code>, 931cannot return. GCC knows this automatically. Some programs define 932their own functions that never return. You can declare them 933<code>noreturn</code> to tell the compiler this fact. For example, 934 935 <pre class="smallexample"> void fatal () __attribute__ ((noreturn)); 936 937 void 938 fatal (/* <span class="roman">...</span> */) 939 { 940 /* <span class="roman">...</span> */ /* <span class="roman">Print error message.</span> */ /* <span class="roman">...</span> */ 941 exit (1); 942 } 943</pre> 944 <p>The <code>noreturn</code> keyword tells the compiler to assume that 945<code>fatal</code> cannot return. It can then optimize without regard to what 946would happen if <code>fatal</code> ever did return. This makes slightly 947better code. More importantly, it helps avoid spurious warnings of 948uninitialized variables. 949 950 <p>The <code>noreturn</code> keyword does not affect the exceptional path when that 951applies: a <code>noreturn</code>-marked function may still return to the caller 952by throwing an exception or calling <code>longjmp</code>. 953 954 <p>Do not assume that registers saved by the calling function are 955restored before calling the <code>noreturn</code> function. 956 957 <p>It does not make sense for a <code>noreturn</code> function to have a return 958type other than <code>void</code>. 959 960 <p>The attribute <code>noreturn</code> is not implemented in GCC versions 961earlier than 2.5. An alternative way to declare that a function does 962not return, which works in the current version and in some older 963versions, is as follows: 964 965 <pre class="smallexample"> typedef void voidfn (); 966 967 volatile voidfn fatal; 968</pre> 969 <p>This approach does not work in GNU C++. 970 971 <br><dt><code>nothrow</code><dd><a name="index-g_t_0040code_007bnothrow_007d-function-attribute-2479"></a>The <code>nothrow</code> attribute is used to inform the compiler that a 972function cannot throw an exception. For example, most functions in 973the standard C library can be guaranteed not to throw an exception 974with the notable exceptions of <code>qsort</code> and <code>bsearch</code> that 975take function pointer arguments. The <code>nothrow</code> attribute is not 976implemented in GCC versions earlier than 3.3. 977 978 <br><dt><code>optimize</code><dd><a name="index-g_t_0040code_007boptimize_007d-function-attribute-2480"></a>The <code>optimize</code> attribute is used to specify that a function is to 979be compiled with different optimization options than specified on the 980command line. Arguments can either be numbers or strings. Numbers 981are assumed to be an optimization level. Strings that begin with 982<code>O</code> are assumed to be an optimization option, while other options 983are assumed to be used with a <code>-f</code> prefix. You can also use the 984‘<samp><span class="samp">#pragma GCC optimize</span></samp>’ pragma to set the optimization options 985that affect more than one function. 986See <a href="Function-Specific-Option-Pragmas.html#Function-Specific-Option-Pragmas">Function Specific Option Pragmas</a>, for details about the 987‘<samp><span class="samp">#pragma GCC optimize</span></samp>’ pragma. 988 989 <p>This can be used for instance to have frequently executed functions 990compiled with more aggressive optimization options that produce faster 991and larger code, while other functions can be called with less 992aggressive options. 993 994 <br><dt><code>pcs</code><dd><a name="index-g_t_0040code_007bpcs_007d-function-attribute-2481"></a> 995The <code>pcs</code> attribute can be used to control the calling convention 996used for a function on ARM. The attribute takes an argument that specifies 997the calling convention to use. 998 999 <p>When compiling using the AAPCS ABI (or a variant of that) then valid 1000values for the argument are <code>"aapcs"</code> and <code>"aapcs-vfp"</code>. In 1001order to use a variant other than <code>"aapcs"</code> then the compiler must 1002be permitted to use the appropriate co-processor registers (i.e., the 1003VFP registers must be available in order to use <code>"aapcs-vfp"</code>). 1004For example, 1005 1006 <pre class="smallexample"> /* Argument passed in r0, and result returned in r0+r1. */ 1007 double f2d (float) __attribute__((pcs("aapcs"))); 1008</pre> 1009 <p>Variadic functions always use the <code>"aapcs"</code> calling convention and 1010the compiler will reject attempts to specify an alternative. 1011 1012 <br><dt><code>pure</code><dd><a name="index-g_t_0040code_007bpure_007d-function-attribute-2482"></a>Many functions have no effects except the return value and their 1013return value depends only on the parameters and/or global variables. 1014Such a function can be subject 1015to common subexpression elimination and loop optimization just as an 1016arithmetic operator would be. These functions should be declared 1017with the attribute <code>pure</code>. For example, 1018 1019 <pre class="smallexample"> int square (int) __attribute__ ((pure)); 1020</pre> 1021 <p class="noindent">says that the hypothetical function <code>square</code> is safe to call 1022fewer times than the program says. 1023 1024 <p>Some of common examples of pure functions are <code>strlen</code> or <code>memcmp</code>. 1025Interesting non-pure functions are functions with infinite loops or those 1026depending on volatile memory or other system resource, that may change between 1027two consecutive calls (such as <code>feof</code> in a multithreading environment). 1028 1029 <p>The attribute <code>pure</code> is not implemented in GCC versions earlier 1030than 2.96. 1031 1032 <br><dt><code>hot</code><dd><a name="index-g_t_0040code_007bhot_007d-function-attribute-2483"></a>The <code>hot</code> attribute is used to inform the compiler that a function is a 1033hot spot of the compiled program. The function is optimized more aggressively 1034and on many target it is placed into special subsection of the text section so 1035all hot functions appears close together improving locality. 1036 1037 <p>When profile feedback is available, via <samp><span class="option">-fprofile-use</span></samp>, hot functions 1038are automatically detected and this attribute is ignored. 1039 1040 <p>The <code>hot</code> attribute is not implemented in GCC versions earlier 1041than 4.3. 1042 1043 <br><dt><code>cold</code><dd><a name="index-g_t_0040code_007bcold_007d-function-attribute-2484"></a>The <code>cold</code> attribute is used to inform the compiler that a function is 1044unlikely executed. The function is optimized for size rather than speed and on 1045many targets it is placed into special subsection of the text section so all 1046cold functions appears close together improving code locality of non-cold parts 1047of program. The paths leading to call of cold functions within code are marked 1048as unlikely by the branch prediction mechanism. It is thus useful to mark 1049functions used to handle unlikely conditions, such as <code>perror</code>, as cold to 1050improve optimization of hot functions that do call marked functions in rare 1051occasions. 1052 1053 <p>When profile feedback is available, via <samp><span class="option">-fprofile-use</span></samp>, hot functions 1054are automatically detected and this attribute is ignored. 1055 1056 <p>The <code>cold</code> attribute is not implemented in GCC versions earlier than 4.3. 1057 1058 <br><dt><code>regparm (</code><var>number</var><code>)</code><dd><a name="index-g_t_0040code_007bregparm_007d-attribute-2485"></a><a name="index-functions-that-are-passed-arguments-in-registers-on-the-386-2486"></a>On the Intel 386, the <code>regparm</code> attribute causes the compiler to 1059pass arguments number one to <var>number</var> if they are of integral type 1060in registers EAX, EDX, and ECX instead of on the stack. Functions that 1061take a variable number of arguments will continue to be passed all of their 1062arguments on the stack. 1063 1064 <p>Beware that on some ELF systems this attribute is unsuitable for 1065global functions in shared libraries with lazy binding (which is the 1066default). Lazy binding will send the first call via resolving code in 1067the loader, which might assume EAX, EDX and ECX can be clobbered, as 1068per the standard calling conventions. Solaris 8 is affected by this. 1069GNU systems with GLIBC 2.1 or higher, and FreeBSD, are believed to be 1070safe since the loaders there save EAX, EDX and ECX. (Lazy binding can be 1071disabled with the linker or the loader if desired, to avoid the 1072problem.) 1073 1074 <br><dt><code>sseregparm</code><dd><a name="index-g_t_0040code_007bsseregparm_007d-attribute-2487"></a>On the Intel 386 with SSE support, the <code>sseregparm</code> attribute 1075causes the compiler to pass up to 3 floating point arguments in 1076SSE registers instead of on the stack. Functions that take a 1077variable number of arguments will continue to pass all of their 1078floating point arguments on the stack. 1079 1080 <br><dt><code>force_align_arg_pointer</code><dd><a name="index-g_t_0040code_007bforce_005falign_005farg_005fpointer_007d-attribute-2488"></a>On the Intel x86, the <code>force_align_arg_pointer</code> attribute may be 1081applied to individual function definitions, generating an alternate 1082prologue and epilogue that realigns the runtime stack if necessary. 1083This supports mixing legacy codes that run with a 4-byte aligned stack 1084with modern codes that keep a 16-byte stack for SSE compatibility. 1085 1086 <br><dt><code>resbank</code><dd><a name="index-g_t_0040code_007bresbank_007d-attribute-2489"></a>On the SH2A target, this attribute enables the high-speed register 1087saving and restoration using a register bank for <code>interrupt_handler</code> 1088routines. Saving to the bank is performed automatically after the CPU 1089accepts an interrupt that uses a register bank. 1090 1091 <p>The nineteen 32-bit registers comprising general register R0 to R14, 1092control register GBR, and system registers MACH, MACL, and PR and the 1093vector table address offset are saved into a register bank. Register 1094banks are stacked in first-in last-out (FILO) sequence. Restoration 1095from the bank is executed by issuing a RESBANK instruction. 1096 1097 <br><dt><code>returns_twice</code><dd><a name="index-g_t_0040code_007breturns_005ftwice_007d-attribute-2490"></a>The <code>returns_twice</code> attribute tells the compiler that a function may 1098return more than one time. The compiler will ensure that all registers 1099are dead before calling such a function and will emit a warning about 1100the variables that may be clobbered after the second return from the 1101function. Examples of such functions are <code>setjmp</code> and <code>vfork</code>. 1102The <code>longjmp</code>-like counterpart of such function, if any, might need 1103to be marked with the <code>noreturn</code> attribute. 1104 1105 <br><dt><code>saveall</code><dd><a name="index-save-all-registers-on-the-Blackfin_002c-H8_002f300_002c-H8_002f300H_002c-and-H8S-2491"></a>Use this attribute on the Blackfin, H8/300, H8/300H, and H8S to indicate that 1106all registers except the stack pointer should be saved in the prologue 1107regardless of whether they are used or not. 1108 1109 <br><dt><code>save_volatiles</code><dd><a name="index-save-volatile-registers-on-the-MicroBlaze-2492"></a>Use this attribute on the MicroBlaze to indicate that the function is 1110an interrupt handler. All volatile registers (in addition to non-volatile 1111registers) will be saved in the function prologue. If the function is a leaf 1112function, only volatiles used by the function are saved. A normal function 1113return is generated instead of a return from interrupt. 1114 1115 <br><dt><code>section ("</code><var>section-name</var><code>")</code><dd><a name="index-g_t_0040code_007bsection_007d-function-attribute-2493"></a>Normally, the compiler places the code it generates in the <code>text</code> section. 1116Sometimes, however, you need additional sections, or you need certain 1117particular functions to appear in special sections. The <code>section</code> 1118attribute specifies that a function lives in a particular section. 1119For example, the declaration: 1120 1121 <pre class="smallexample"> extern void foobar (void) __attribute__ ((section ("bar"))); 1122</pre> 1123 <p class="noindent">puts the function <code>foobar</code> in the <code>bar</code> section. 1124 1125 <p>Some file formats do not support arbitrary sections so the <code>section</code> 1126attribute is not available on all platforms. 1127If you need to map the entire contents of a module to a particular 1128section, consider using the facilities of the linker instead. 1129 1130 <br><dt><code>sentinel</code><dd><a name="index-g_t_0040code_007bsentinel_007d-function-attribute-2494"></a>This function attribute ensures that a parameter in a function call is 1131an explicit <code>NULL</code>. The attribute is only valid on variadic 1132functions. By default, the sentinel is located at position zero, the 1133last parameter of the function call. If an optional integer position 1134argument P is supplied to the attribute, the sentinel must be located at 1135position P counting backwards from the end of the argument list. 1136 1137 <pre class="smallexample"> __attribute__ ((sentinel)) 1138 is equivalent to 1139 __attribute__ ((sentinel(0))) 1140</pre> 1141 <p>The attribute is automatically set with a position of 0 for the built-in 1142functions <code>execl</code> and <code>execlp</code>. The built-in function 1143<code>execle</code> has the attribute set with a position of 1. 1144 1145 <p>A valid <code>NULL</code> in this context is defined as zero with any pointer 1146type. If your system defines the <code>NULL</code> macro with an integer type 1147then you need to add an explicit cast. GCC replaces <code>stddef.h</code> 1148with a copy that redefines NULL appropriately. 1149 1150 <p>The warnings for missing or incorrect sentinels are enabled with 1151<samp><span class="option">-Wformat</span></samp>. 1152 1153 <br><dt><code>short_call</code><dd>See long_call/short_call. 1154 1155 <br><dt><code>shortcall</code><dd>See longcall/shortcall. 1156 1157 <br><dt><code>signal</code><dd><a name="index-signal-handler-functions-on-the-AVR-processors-2495"></a>Use this attribute on the AVR to indicate that the specified 1158function is a signal handler. The compiler will generate function 1159entry and exit sequences suitable for use in a signal handler when this 1160attribute is present. Interrupts will be disabled inside the function. 1161 1162 <br><dt><code>sp_switch</code><dd>Use this attribute on the SH to indicate an <code>interrupt_handler</code> 1163function should switch to an alternate stack. It expects a string 1164argument that names a global variable holding the address of the 1165alternate stack. 1166 1167 <pre class="smallexample"> void *alt_stack; 1168 void f () __attribute__ ((interrupt_handler, 1169 sp_switch ("alt_stack"))); 1170</pre> 1171 <br><dt><code>stdcall</code><dd><a name="index-functions-that-pop-the-argument-stack-on-the-386-2496"></a>On the Intel 386, the <code>stdcall</code> attribute causes the compiler to 1172assume that the called function will pop off the stack space used to 1173pass arguments, unless it takes a variable number of arguments. 1174 1175 <br><dt><code>syscall_linkage</code><dd><a name="index-g_t_0040code_007bsyscall_005flinkage_007d-attribute-2497"></a>This attribute is used to modify the IA64 calling convention by marking 1176all input registers as live at all function exits. This makes it possible 1177to restart a system call after an interrupt without having to save/restore 1178the input registers. This also prevents kernel data from leaking into 1179application code. 1180 1181 <br><dt><code>target</code><dd><a name="index-g_t_0040code_007btarget_007d-function-attribute-2498"></a>The <code>target</code> attribute is used to specify that a function is to 1182be compiled with different target options than specified on the 1183command line. This can be used for instance to have functions 1184compiled with a different ISA (instruction set architecture) than the 1185default. You can also use the ‘<samp><span class="samp">#pragma GCC target</span></samp>’ pragma to set 1186more than one function to be compiled with specific target options. 1187See <a href="Function-Specific-Option-Pragmas.html#Function-Specific-Option-Pragmas">Function Specific Option Pragmas</a>, for details about the 1188‘<samp><span class="samp">#pragma GCC target</span></samp>’ pragma. 1189 1190 <p>For instance on a 386, you could compile one function with 1191<code>target("sse4.1,arch=core2")</code> and another with 1192<code>target("sse4a,arch=amdfam10")</code> that would be equivalent to 1193compiling the first function with <samp><span class="option">-msse4.1</span></samp> and 1194<samp><span class="option">-march=core2</span></samp> options, and the second function with 1195<samp><span class="option">-msse4a</span></samp> and <samp><span class="option">-march=amdfam10</span></samp> options. It is up to the 1196user to make sure that a function is only invoked on a machine that 1197supports the particular ISA it was compiled for (for example by using 1198<code>cpuid</code> on 386 to determine what feature bits and architecture 1199family are used). 1200 1201 <pre class="smallexample"> int core2_func (void) __attribute__ ((__target__ ("arch=core2"))); 1202 int sse3_func (void) __attribute__ ((__target__ ("sse3"))); 1203</pre> 1204 <p>On the 386, the following options are allowed: 1205 1206 <dl> 1207<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-2499"></a>Enable/disable the generation of the advanced bit instructions. 1208 1209 <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-2500"></a>Enable/disable the generation of the AES instructions. 1210 1211 <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-2501"></a>Enable/disable the generation of the MMX instructions. 1212 1213 <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-2502"></a>Enable/disable the generation of the PCLMUL instructions. 1214 1215 <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-2503"></a>Enable/disable the generation of the POPCNT instruction. 1216 1217 <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-2504"></a>Enable/disable the generation of the SSE instructions. 1218 1219 <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-2505"></a>Enable/disable the generation of the SSE2 instructions. 1220 1221 <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-2506"></a>Enable/disable the generation of the SSE3 instructions. 1222 1223 <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-2507"></a>Enable/disable the generation of the SSE4 instructions (both SSE4.1 1224and SSE4.2). 1225 1226 <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-2508"></a>Enable/disable the generation of the sse4.1 instructions. 1227 1228 <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-2509"></a>Enable/disable the generation of the sse4.2 instructions. 1229 1230 <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-2510"></a>Enable/disable the generation of the SSE4A instructions. 1231 1232 <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-2511"></a>Enable/disable the generation of the FMA4 instructions. 1233 1234 <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-2512"></a>Enable/disable the generation of the XOP instructions. 1235 1236 <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-2513"></a>Enable/disable the generation of the LWP instructions. 1237 1238 <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-2514"></a>Enable/disable the generation of the SSSE3 instructions. 1239 1240 <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-2515"></a>Enable/disable the generation of the CLD before string moves. 1241 1242 <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-2516"></a>Enable/disable the generation of the <code>sin</code>, <code>cos</code>, and 1243<code>sqrt</code> instructions on the 387 floating point unit. 1244 1245 <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-2517"></a>Enable/disable the generation of the fused multiply/add instructions. 1246 1247 <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-2518"></a>Enable/disable the generation of floating point that depends on IEEE arithmetic. 1248 1249 <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-2519"></a>Enable/disable inlining of string operations. 1250 1251 <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-2520"></a>Enable/disable the generation of the inline code to do small string 1252operations and calling the library routines for large operations. 1253 1254 <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-2521"></a>Do/do not align destination of inlined string operations. 1255 1256 <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-2522"></a>Enable/disable the generation of RCPSS, RCPPS, RSQRTSS and RSQRTPS 1257instructions followed an additional Newton-Raphson step instead of 1258doing a floating point division. 1259 1260 <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-2523"></a>Specify the architecture to generate code for in compiling the function. 1261 1262 <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-2524"></a>Specify the architecture to tune for in compiling the function. 1263 1264 <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-2525"></a>Specify which floating point unit to use. The 1265<code>target("fpmath=sse,387")</code> option must be specified as 1266<code>target("fpmath=sse+387")</code> because the comma would separate 1267different options. 1268</dl> 1269 1270 <p>On the PowerPC, the following options are allowed: 1271 1272 <dl> 1273<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-2526"></a>Generate code that uses (does not use) AltiVec instructions. In 127432-bit code, you cannot enable Altivec instructions unless 1275<samp><span class="option">-mabi=altivec</span></samp> was used on the command line. 1276 1277 <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-2527"></a>Generate code that uses (does not use) the compare bytes instruction 1278implemented on the POWER6 processor and other processors that support 1279the PowerPC V2.05 architecture. 1280 1281 <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-2528"></a>Generate code that uses (does not use) the string-search ‘<samp><span class="samp">dlmzb</span></samp>’ 1282instruction on the IBM 405, 440, 464 and 476 processors. This instruction is 1283generated by default when targetting those processors. 1284 1285 <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-2529"></a>Generate code that uses (does not use) the FP round to integer 1286instructions implemented on the POWER5+ processor and other processors 1287that support the PowerPC V2.03 architecture. 1288 1289 <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-2530"></a>Generate code that uses (does not use) the decimal floating point 1290instructions implemented on some POWER processors. 1291 1292 <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-2531"></a>Generate code that uses (does not use) ISEL instruction. 1293 1294 <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-2532"></a>Generate code that uses (does not use) the move from condition 1295register field instruction implemented on the POWER4 processor and 1296other processors that support the PowerPC V2.01 architecture. 1297 1298 <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-2533"></a>Generate code that uses (does not use) the FP move to/from general 1299purpose register instructions implemented on the POWER6X processor and 1300other processors that support the extended PowerPC V2.05 architecture. 1301 1302 <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-2534"></a>Generate code that uses (does not use) the half-word multiply and 1303multiply-accumulate instructions on the IBM 405, 440, 464 and 476 processors. 1304These instructions are generated by default when targetting those 1305processors. 1306 1307 <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-2535"></a>Generate code that uses (does not use) the load multiple word 1308instructions and the store multiple word instructions. 1309 1310 <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-2536"></a>Generate code that uses (does not use) the load or store instructions 1311that update the base register to the address of the calculated memory 1312location. 1313 1314 <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-2537"></a>Generate code that uses (does not use) the popcount and double 1315precision FP reciprocal estimate instruction implemented on the POWER5 1316processor and other processors that support the PowerPC V2.02 1317architecture. 1318 1319 <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-2538"></a>Generate code that uses (does not use) the popcount instruction 1320implemented on the POWER7 processor and other processors that support 1321the PowerPC V2.06 architecture. 1322 1323 <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-2539"></a>Generate code that uses (does not use) the optional PowerPC 1324architecture instructions in the Graphics group, including 1325floating-point select. 1326 1327 <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-2540"></a>Generate code that uses (does not use) the optional PowerPC 1328architecture instructions in the General Purpose group, including 1329floating-point square root. 1330 1331 <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-2541"></a>Assume (do not assume) that the reciprocal estimate instructions 1332provide higher precision estimates than is mandated by the powerpc 1333ABI. 1334 1335 <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-2542"></a>Generate code that uses (does not use) the load string instructions 1336and the store string word instructions to save multiple registers and 1337do small block moves. 1338 1339 <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-2543"></a>Generate code that uses (does not use) vector/scalar (VSX) 1340instructions, and also enable the use of built-in functions that allow 1341more direct access to the VSX instruction set. In 32-bit code, you 1342cannot enable VSX or Altivec instructions unless 1343<samp><span class="option">-mabi=altivec</span></samp> was used on the command line. 1344 1345 <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-2544"></a>Generate (do not generate) the <code>friz</code> instruction when the 1346<samp><span class="option">-funsafe-math-optimizations</span></samp> option is used to optimize 1347rounding a floating point value to 64-bit integer and back to floating 1348point. The <code>friz</code> instruction does not return the same value if 1349the floating point number is too large to fit in an integer. 1350 1351 <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-2545"></a>Generate code that tries to avoid (not avoid) the use of indexed load 1352or store instructions. 1353 1354 <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-2546"></a>Generate code that uses (does not use) the generation of PAIRED simd 1355instructions. 1356 1357 <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-2547"></a>Generate code that assumes (does not assume) that all calls are far 1358away so that a longer more expensive calling sequence is required. 1359 1360 <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-2548"></a>Specify the architecture to generate code for when compiling the 1361function. If you select the <code>"target("cpu=power7)"</code> attribute when 1362generating 32-bit code, VSX and Altivec instructions are not generated 1363unless you use the <samp><span class="option">-mabi=altivec</span></samp> option on the command line. 1364 1365 <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-2549"></a>Specify the architecture to tune for when compiling the function. If 1366you do not specify the <code>target("tune=</code><var>TUNE</var><code>")</code> attribute and 1367you do specify the <code>target("cpu=</code><var>CPU</var><code>")</code> attribute, 1368compilation will tune for the <var>CPU</var> architecture, and not the 1369default tuning specified on the command line. 1370</dl> 1371 1372 <p>On the 386/x86_64 and PowerPC backends, you can use either multiple 1373strings to specify multiple options, or you can separate the option 1374with a comma (<code>,</code>). 1375 1376 <p>On the 386/x86_64 and PowerPC backends, the inliner will not inline a 1377function that has different target options than the caller, unless the 1378callee has a subset of the target options of the caller. For example 1379a function declared with <code>target("sse3")</code> can inline a function 1380with <code>target("sse2")</code>, since <code>-msse3</code> implies <code>-msse2</code>. 1381 1382 <p>The <code>target</code> attribute is not implemented in GCC versions earlier 1383than 4.4 for the i386/x86_64 and 4.6 for the PowerPC backends. It is 1384not currently implemented for other backends. 1385 1386 <br><dt><code>tiny_data</code><dd><a name="index-tiny-data-section-on-the-H8_002f300H-and-H8S-2550"></a>Use this attribute on the H8/300H and H8S to indicate that the specified 1387variable should be placed into the tiny data section. 1388The compiler will generate more efficient code for loads and stores 1389on data in the tiny data section. Note the tiny data area is limited to 1390slightly under 32kbytes of data. 1391 1392 <br><dt><code>trap_exit</code><dd>Use this attribute on the SH for an <code>interrupt_handler</code> to return using 1393<code>trapa</code> instead of <code>rte</code>. This attribute expects an integer 1394argument specifying the trap number to be used. 1395 1396 <br><dt><code>unused</code><dd><a name="index-g_t_0040code_007bunused_007d-attribute_002e-2551"></a>This attribute, attached to a function, means that the function is meant 1397to be possibly unused. GCC will not produce a warning for this 1398function. 1399 1400 <br><dt><code>used</code><dd><a name="index-g_t_0040code_007bused_007d-attribute_002e-2552"></a>This attribute, attached to a function, means that code must be emitted 1401for the function even if it appears that the function is not referenced. 1402This is useful, for example, when the function is referenced only in 1403inline assembly. 1404 1405 <br><dt><code>version_id</code><dd><a name="index-g_t_0040code_007bversion_005fid_007d-attribute-2553"></a>This IA64 HP-UX attribute, attached to a global variable or function, renames a 1406symbol to contain a version string, thus allowing for function level 1407versioning. HP-UX system header files may use version level functioning 1408for some system calls. 1409 1410 <pre class="smallexample"> extern int foo () __attribute__((version_id ("20040821"))); 1411</pre> 1412 <p>Calls to <var>foo</var> will be mapped to calls to <var>foo{20040821}</var>. 1413 1414 <br><dt><code>visibility ("</code><var>visibility_type</var><code>")</code><dd><a name="index-g_t_0040code_007bvisibility_007d-attribute-2554"></a>This attribute affects the linkage of the declaration to which it is attached. 1415There are four supported <var>visibility_type</var> values: default, 1416hidden, protected or internal visibility. 1417 1418 <pre class="smallexample"> void __attribute__ ((visibility ("protected"))) 1419 f () { /* <span class="roman">Do something.</span> */; } 1420 int i __attribute__ ((visibility ("hidden"))); 1421</pre> 1422 <p>The possible values of <var>visibility_type</var> correspond to the 1423visibility settings in the ELF gABI. 1424 1425 <dl> 1426<!-- keep this list of visibilities in alphabetical order. --> 1427 1428 <dt><dfn>default</dfn><dd>Default visibility is the normal case for the object file format. 1429This value is available for the visibility attribute to override other 1430options that may change the assumed visibility of entities. 1431 1432 <p>On ELF, default visibility means that the declaration is visible to other 1433modules and, in shared libraries, means that the declared entity may be 1434overridden. 1435 1436 <p>On Darwin, default visibility means that the declaration is visible to 1437other modules. 1438 1439 <p>Default visibility corresponds to “external linkage” in the language. 1440 1441 <br><dt><dfn>hidden</dfn><dd>Hidden visibility indicates that the entity declared will have a new 1442form of linkage, which we'll call “hidden linkage”. Two 1443declarations of an object with hidden linkage refer to the same object 1444if they are in the same shared object. 1445 1446 <br><dt><dfn>internal</dfn><dd>Internal visibility is like hidden visibility, but with additional 1447processor specific semantics. Unless otherwise specified by the 1448psABI, GCC defines internal visibility to mean that a function is 1449<em>never</em> called from another module. Compare this with hidden 1450functions which, while they cannot be referenced directly by other 1451modules, can be referenced indirectly via function pointers. By 1452indicating that a function cannot be called from outside the module, 1453GCC may for instance omit the load of a PIC register since it is known 1454that the calling function loaded the correct value. 1455 1456 <br><dt><dfn>protected</dfn><dd>Protected visibility is like default visibility except that it 1457indicates that references within the defining module will bind to the 1458definition in that module. That is, the declared entity cannot be 1459overridden by another module. 1460 1461 </dl> 1462 1463 <p>All visibilities are supported on many, but not all, ELF targets 1464(supported when the assembler supports the ‘<samp><span class="samp">.visibility</span></samp>’ 1465pseudo-op). Default visibility is supported everywhere. Hidden 1466visibility is supported on Darwin targets. 1467 1468 <p>The visibility attribute should be applied only to declarations which 1469would otherwise have external linkage. The attribute should be applied 1470consistently, so that the same entity should not be declared with 1471different settings of the attribute. 1472 1473 <p>In C++, the visibility attribute applies to types as well as functions 1474and objects, because in C++ types have linkage. A class must not have 1475greater visibility than its non-static data member types and bases, 1476and class members default to the visibility of their class. Also, a 1477declaration without explicit visibility is limited to the visibility 1478of its type. 1479 1480 <p>In C++, you can mark member functions and static member variables of a 1481class with the visibility attribute. This is useful if you know a 1482particular method or static member variable should only be used from 1483one shared object; then you can mark it hidden while the rest of the 1484class has default visibility. Care must be taken to avoid breaking 1485the One Definition Rule; for example, it is usually not useful to mark 1486an inline method as hidden without marking the whole class as hidden. 1487 1488 <p>A C++ namespace declaration can also have the visibility attribute. 1489This attribute applies only to the particular namespace body, not to 1490other definitions of the same namespace; it is equivalent to using 1491‘<samp><span class="samp">#pragma GCC visibility</span></samp>’ before and after the namespace 1492definition (see <a href="Visibility-Pragmas.html#Visibility-Pragmas">Visibility Pragmas</a>). 1493 1494 <p>In C++, if a template argument has limited visibility, this 1495restriction is implicitly propagated to the template instantiation. 1496Otherwise, template instantiations and specializations default to the 1497visibility of their template. 1498 1499 <p>If both the template and enclosing class have explicit visibility, the 1500visibility from the template is used. 1501 1502 <br><dt><code>vliw</code><dd><a name="index-g_t_0040code_007bvliw_007d-attribute-2555"></a>On MeP, the <code>vliw</code> attribute tells the compiler to emit 1503instructions in VLIW mode instead of core mode. Note that this 1504attribute is not allowed unless a VLIW coprocessor has been configured 1505and enabled through command line options. 1506 1507 <br><dt><code>warn_unused_result</code><dd><a name="index-g_t_0040code_007bwarn_005funused_005fresult_007d-attribute-2556"></a>The <code>warn_unused_result</code> attribute causes a warning to be emitted 1508if a caller of the function with this attribute does not use its 1509return value. This is useful for functions where not checking 1510the result is either a security problem or always a bug, such as 1511<code>realloc</code>. 1512 1513 <pre class="smallexample"> int fn () __attribute__ ((warn_unused_result)); 1514 int foo () 1515 { 1516 if (fn () < 0) return -1; 1517 fn (); 1518 return 0; 1519 } 1520</pre> 1521 <p>results in warning on line 5. 1522 1523 <br><dt><code>weak</code><dd><a name="index-g_t_0040code_007bweak_007d-attribute-2557"></a>The <code>weak</code> attribute causes the declaration to be emitted as a weak 1524symbol rather than a global. This is primarily useful in defining 1525library functions which can be overridden in user code, though it can 1526also be used with non-function declarations. Weak symbols are supported 1527for ELF targets, and also for a.out targets when using the GNU assembler 1528and linker. 1529 1530 <br><dt><code>weakref</code><dt><code>weakref ("</code><var>target</var><code>")</code><dd><a name="index-g_t_0040code_007bweakref_007d-attribute-2558"></a>The <code>weakref</code> attribute marks a declaration as a weak reference. 1531Without arguments, it should be accompanied by an <code>alias</code> attribute 1532naming the target symbol. Optionally, the <var>target</var> may be given as 1533an argument to <code>weakref</code> itself. In either case, <code>weakref</code> 1534implicitly marks the declaration as <code>weak</code>. Without a 1535<var>target</var>, given as an argument to <code>weakref</code> or to <code>alias</code>, 1536<code>weakref</code> is equivalent to <code>weak</code>. 1537 1538 <pre class="smallexample"> static int x() __attribute__ ((weakref ("y"))); 1539 /* is equivalent to... */ 1540 static int x() __attribute__ ((weak, weakref, alias ("y"))); 1541 /* and to... */ 1542 static int x() __attribute__ ((weakref)); 1543 static int x() __attribute__ ((alias ("y"))); 1544</pre> 1545 <p>A weak reference is an alias that does not by itself require a 1546definition to be given for the target symbol. If the target symbol is 1547only referenced through weak references, then it becomes a <code>weak</code> 1548undefined symbol. If it is directly referenced, however, then such 1549strong references prevail, and a definition will be required for the 1550symbol, not necessarily in the same translation unit. 1551 1552 <p>The effect is equivalent to moving all references to the alias to a 1553separate translation unit, renaming the alias to the aliased symbol, 1554declaring it as weak, compiling the two separate translation units and 1555performing a reloadable link on them. 1556 1557 <p>At present, a declaration to which <code>weakref</code> is attached can 1558only be <code>static</code>. 1559 1560 </dl> 1561 1562 <p>You can specify multiple attributes in a declaration by separating them 1563by commas within the double parentheses or by immediately following an 1564attribute declaration with another attribute declaration. 1565 1566 <p><a name="index-g_t_0040code_007b_0023pragma_007d_002c-reason-for-not-using-2559"></a><a name="index-pragma_002c-reason-for-not-using-2560"></a>Some people object to the <code>__attribute__</code> feature, suggesting that 1567ISO C's <code>#pragma</code> should be used instead. At the time 1568<code>__attribute__</code> was designed, there were two reasons for not doing 1569this. 1570 1571 <ol type=1 start=1> 1572<li>It is impossible to generate <code>#pragma</code> commands from a macro. 1573 1574 <li>There is no telling what the same <code>#pragma</code> might mean in another 1575compiler. 1576 </ol> 1577 1578 <p>These two reasons applied to almost any application that might have been 1579proposed for <code>#pragma</code>. It was basically a mistake to use 1580<code>#pragma</code> for <em>anything</em>. 1581 1582 <p>The ISO C99 standard includes <code>_Pragma</code>, which now allows pragmas 1583to be generated from macros. In addition, a <code>#pragma GCC</code> 1584namespace is now in use for GCC-specific pragmas. However, it has been 1585found convenient to use <code>__attribute__</code> to achieve a natural 1586attachment of attributes to their corresponding declarations, whereas 1587<code>#pragma GCC</code> is of use for constructs that do not naturally form 1588part of the grammar. See <a href="../cpp/Other-Directives.html#Other-Directives">Miscellaneous Preprocessing Directives</a>. 1589 1590 </body></html> 1591 1592