5.24 Declaring Attributes of Functions【轉】

You may also specify attributes with `__' preceding and following each keyword. This allows you to use them in header files without being concerned about a possible macro of the same name. For example, you may use <code>__noreturn__</code> instead of <code>noreturn</code>.

<dl></dl>

<dt></dt>

<code>alias ("</code>target<code>")</code>

<dd></dd>

declares `f' to be a weak alias for `__f'. In C++, the mangled name for the target must be used. It is an error if `__f' is not defined in the same translation unit.

Not all target machines support this attribute. 

<dt><code>always_inline</code></dt>

<dt><code>cdecl</code></dt>

<dt><code>const</code></dt>

The attribute <code>const</code> is not implemented in GCC versions earlier than 2.5. An alternative way to declare that a function has no side effects, which works in the current version and in some older versions, is as follows:

This approach does not work in GNU C++ from 2.6.0 on, since the language specifies that the `const' must be attached to the return value. 

<dt><code>constructor</code></dt>

<dt><code>destructor</code></dt>

These attributes are not currently implemented for Objective-C. 

<dt><code>deprecated</code></dt>

results in a warning on line 3 but not line 2.

<dt><code>dllexport</code></dt>

You can use <code>__declspec(dllexport)</code> as a synonym for <code>__attribute__ ((dllexport))</code> for compatibility with other compilers.

On systems that support the <code>visibility</code> attribute, this attribute also implies “default” visibility, unless a <code>visibility</code> attribute is explicitly specified. You should avoid the use of <code>dllexport</code>with “hidden” or “internal” visibility; in the future GCC may issue an error for those cases.

Currently, the <code>dllexport</code> attribute is ignored for inlined functions, unless the -fkeep-inline-functions flag has been used. The attribute is also ignored for undefined symbols.

When applied to C++ classes, the attribute marks defined non-inlined member functions and static data members as exports. Static consts initialized in-class are not marked unless they are also defined out-of-class.

For Microsoft Windows targets there are alternative methods for including the symbol in the DLL's export table such as using a .def file with an <code>EXPORTS</code> section or, with GNU ld, using the --export-all linker flag. 

<dt><code>dllimport</code></dt>

You can use <code>__declspec(dllimport)</code> as a synonym for <code>__attribute__ ((dllimport))</code> for compatibility with other compilers.

Currently, the attribute is ignored for inlined functions. If the attribute is applied to a symbol definition, an error is reported. If a symbol previously declared <code>dllimport</code> is later defined, the attribute is ignored in subsequent references, and a warning is emitted. The attribute is also overridden by a subsequent declaration as <code>dllexport</code>.

When applied to C++ classes, the attribute marks non-inlined member functions and static data members as imports. However, the attribute is ignored for virtual methods to allow creation of vtables using thunks.

On the SH Symbian OS target the <code>dllimport</code> attribute also has another affect—it can cause the vtable and run-time type information for a class to be exported. This happens when the class has a dllimport'ed constructor or a non-inline, non-pure virtual function and, for either of those two conditions, the class also has a inline constructor or destructor and has a key function that is defined in the current translation unit.

For Microsoft Windows based targets the use of the <code>dllimport</code> attribute on functions is not necessary, but provides a small performance benefit by eliminating a thunk in the DLL. The use of the<code>dllimport</code> attribute on imported variables was required on older versions of the GNU linker, but can now be avoided by passing the --enable-auto-import switch to the GNU linker. As with functions, using the attribute for a variable eliminates a thunk in the DLL.

One drawback to using this attribute is that a pointer to a function or variable marked as <code>dllimport</code> cannot be used as a constant address. On Microsoft Windows targets, the attribute can be disabled for functions by setting the -mnop-fun-dllimport flag. 

<dt><code>eightbit_data</code></dt>

You must use GAS and GLD from GNU binutils version 2.7 or later for this attribute to work correctly. 

<dt><code>far</code></dt>

On 68HC12 the compiler will use the <code>call</code> and <code>rtc</code> instructions to call and return from a function.

On 68HC11 the compiler will generate a sequence of instructions to invoke a board-specific routine to switch the memory bank and call the real function. The board-specific routine simulates a<code>call</code>. At the end of a function, it will jump to a board-specific routine instead of using <code>rts</code>. The board-specific return routine simulates the <code>rtc</code>. 

<dt><code>fastcall</code></dt>

<code>format (</code>archetype<code>, </code>string-index<code>, </code>first-to-check<code>)</code>

causes the compiler to check the arguments in calls to <code>my_printf</code> for consistency with the <code>printf</code> style format string argument <code>my_format</code>.

The parameter archetype determines how the format string is interpreted, and should be <code>printf</code>, <code>scanf</code>, <code>strftime</code> or <code>strfmon</code>. (You can also use <code>__printf__</code>, <code>__scanf__</code>, <code>__strftime__</code> or <code>__strfmon__</code>.) The parameter string-index specifies which argument is the format string argument (starting from 1), while first-to-check is the number of the first argument to check against the format string. For functions where the arguments are not available to be checked (such as <code>vprintf</code>), specify the third parameter as zero. In this case the compiler only checks the format string for consistency. For <code>strftime</code> formats, the third parameter is required to be zero. Since non-static C++ methods have an implicit <code>this</code> argument, the arguments of such methods should be counted from two, not one, when giving values for string-index and first-to-check.

In the example above, the format string (<code>my_format</code>) is the second argument of the function <code>my_print</code>, and the arguments to check start with the third argument, so the correct parameters for the format attribute are 2 and 3.

<code>format_arg (</code>string-index<code>)</code>

causes the compiler to check the arguments in calls to a <code>printf</code>, <code>scanf</code>, <code>strftime</code> or <code>strfmon</code> type function, whose format string argument is a call to the <code>my_dgettext</code> function, for consistency with the format string argument <code>my_format</code>. If the <code>format_arg</code> attribute had not been specified, all the compiler could tell in such calls to format functions would be that the format string argument is not constant; this would generate a warning when -Wformat-nonliteral is used, but the calls could not be checked without the attribute.

The parameter string-index specifies which argument is the format string argument (starting from one). Since non-static C++ methods have an implicit <code>this</code> argument, the arguments of such methods should be counted from two.

<dt><code>function_vector</code></dt>

<dt><code>interrupt</code></dt>

Note, interrupt handlers for the m68k, H8/300, H8/300H, H8S, and SH processors can be specified via the <code>interrupt_handler</code> attribute.

Note, on the AVR, interrupts will be enabled inside the function.

Note, for the ARM, you can specify the kind of interrupt to be handled by adding an optional parameter to the interrupt attribute like this:

Permissible values for this parameter are: IRQ, FIQ, SWI, ABORT and UNDEF. 

<dt><code>interrupt_handler</code></dt>

<dt><code>long_call/short_call</code></dt>

<dt><code>longcall/shortcall</code></dt>

<dt><code>malloc</code></dt>

<code>model (</code>model-name<code>)</code>

Small model objects live in the lower 16MB of memory (so that their addresses can be loaded with the <code>ld24</code> instruction), and are callable with the <code>bl</code> instruction.

Medium model objects may live anywhere in the 32-bit address space (the compiler will generate <code>seth/add3</code> instructions to load their addresses), and are callable with the <code>bl</code> instruction.

Large model objects may live anywhere in the 32-bit address space (the compiler will generate <code>seth/add3</code> instructions to load their addresses), and may not be reachable with the <code>bl</code> instruction (the compiler will generate the much slower <code>seth/add3/jl</code> instruction sequence).

On IA-64, use this attribute to set the addressability of an object. At present, the only supported identifier for model-name is <code>small</code>, indicating addressability via “small” (22-bit) addresses (so that their addresses can be loaded with the <code>addl</code> instruction). Caveat: such addressing is by definition not position independent and hence this attribute must not be used for objects defined by shared libraries. 

<dt><code>naked</code></dt>

<dt><code>near</code></dt>

<dt><code>no_instrument_function</code></dt>

<dt><code>noinline</code></dt>

<code>nonnull (</code>arg-index<code>, ...)</code>

causes the compiler to check that, in calls to <code>my_memcpy</code>, arguments dest and src are non-null. If the compiler determines that a null pointer is passed in an argument slot marked as non-null, and the -Wnonnull option is enabled, a warning is issued. The compiler may also choose to make optimizations based on the knowledge that certain function arguments will not be null.

If no argument index list is given to the <code>nonnull</code> attribute, all pointer arguments are marked as non-null. To illustrate, the following declaration is equivalent to the previous example:

<dt><code>noreturn</code></dt>

The <code>noreturn</code> keyword tells the compiler to assume that <code>fatal</code> cannot return. It can then optimize without regard to what would happen if <code>fatal</code> ever did return. This makes slightly better code. More importantly, it helps avoid spurious warnings of uninitialized variables.

The <code>noreturn</code> keyword does not affect the exceptional path when that applies: a <code>noreturn</code>-marked function may still return to the caller by throwing an exception or calling <code>longjmp</code>.

Do not assume that registers saved by the calling function are restored before calling the <code>noreturn</code> function.

It does not make sense for a <code>noreturn</code> function to have a return type other than <code>void</code>.

The attribute <code>noreturn</code> is not implemented in GCC versions earlier than 2.5. An alternative way to declare that a function does not return, which works in the current version and in some older versions, is as follows:

This approach does not work in GNU C++. 

<dt><code>nothrow</code></dt>

<dt><code>pure</code></dt>

says that the hypothetical function <code>square</code> is safe to call fewer times than the program says.

Some of common examples of pure functions are <code>strlen</code> or <code>memcmp</code>. Interesting non-pure functions are functions with infinite loops or those depending on volatile memory or other system resource, that may change between two consecutive calls (such as <code>feof</code> in a multithreading environment).

The attribute <code>pure</code> is not implemented in GCC versions earlier than 2.96. 

<code>regparm (</code>number<code>)</code>

Beware that on some ELF systems this attribute is unsuitable for global functions in shared libraries with lazy binding (which is the default). Lazy binding will send the first call via resolving code in the loader, which might assume EAX, EDX and ECX can be clobbered, as per the standard calling conventions. Solaris 8 is affected by this. GNU systems with GLIBC 2.1 or higher, and FreeBSD, are believed to be safe since the loaders there save all registers. (Lazy binding can be disabled with the linker or the loader if desired, to avoid the problem.) 

<dt><code>saveall</code></dt>

<code>section ("</code>section-name<code>")</code>

puts the function <code>foobar</code> in the <code>bar</code> section.

Some file formats do not support arbitrary sections so the <code>section</code> attribute is not available on all platforms. If you need to map the entire contents of a module to a particular section, consider using the facilities of the linker instead. 

<dt><code>sentinel</code></dt>

The attribute is automatically set with a position of 0 for the built-in functions <code>execl</code> and <code>execlp</code>. The built-in function <code>execle</code> has the attribute set with a position of 1.

A valid <code>NULL</code> in this context is defined as zero with any pointer type. If your system defines the <code>NULL</code> macro with an integer type then you need to add an explicit cast. GCC replaces <code>stddef.h</code>with a copy that redefines NULL appropriately.

The warnings for missing or incorrect sentinels are enabled with -Wformat. 

<dt><code>short_call</code></dt>

<dd>See long_call/short_call. </dd>

<dt><code>shortcall</code></dt>

<dd>See longcall/shortcall. </dd>

<dt><code>signal</code></dt>

<dt><code>sp_switch</code></dt>

<dd>Use this attribute on the SH to indicate an <code>interrupt_handler</code> function should switch to an alternate stack. It expects a string argument that names a global variable holding the address of the alternate stack.</dd>

<dt><code>stdcall</code></dt>

<dt><code>tiny_data</code></dt>

<dt><code>trap_exit</code></dt>

<dd>Use this attribute on the SH for an <code>interrupt_handler</code> to return using <code>trapa</code> instead of <code>rte</code>. This attribute expects an integer argument specifying the trap number to be used. </dd>

<dt><code>unused</code></dt>

<dt><code>used</code></dt>

<code>visibility ("</code>visibility_type<code>")</code>

See the ELF gABI for complete details, but the short story is:

<dt>default</dt>

<dd>Default visibility is the normal case for ELF. This value is available for the visibility attribute to override other options that may change the assumed visibility of symbols. </dd>

<dt>hidden</dt>

<dd>Hidden visibility indicates that the symbol will not be placed into the dynamic symbol table, so no other module (executable or shared library) can reference it directly. </dd>

<dt>internal</dt>

<dd>Internal visibility is like hidden visibility, but with additional processor specific semantics. Unless otherwise specified by the psABI, GCC defines internal visibility to mean that the function is never called from another module. Note that hidden symbols, while they cannot be referenced directly by other modules, can be referenced indirectly via function pointers. By indicating that a symbol cannot be called from outside the module, GCC may for instance omit the load of a PIC register since it is known that the calling function loaded the correct value. </dd>

<dt>protected</dt>

<dd>Protected visibility indicates that the symbol will be placed in the dynamic symbol table, but that references within the defining module will bind to the local symbol. That is, the symbol cannot be overridden by another module.</dd>

Not all ELF targets support this attribute. 

<dt><code>warn_unused_result</code></dt>

results in warning on line 5. 

<dt><code>weak</code></dt>

You can specify multiple attributes in a declaration by separating them by commas within the double parentheses or by immediately following an attribute declaration with another attribute declaration.

It is impossible to generate <code>#pragma</code> commands from a macro.

There is no telling what the same <code>#pragma</code> might mean in another compiler.

These two reasons applied to almost any application that might have been proposed for <code>#pragma</code>. It was basically a mistake to use <code>#pragma</code> for anything.

【新浪微網誌】 張昺華--sky

【twitter】 @sky2030_

【facebook】 張昺華 zhangbinghua

本文版權歸作者和部落格園共有，歡迎轉載，但未經作者同意必須保留此段聲明，且在文章頁面明顯位置給出原文連接配接，否則保留追究法律責任的權利.