function-attributes.html

自己收集的linux入门到学懂高级编程书集 包括linux程序设计第三版

both the <code>-mlongcall</code> switch and the <code>#pragma longcall</code>
setting.

     <p>See <a href="RS-6000-and-PowerPC-Options.html#RS%2f6000%20and%20PowerPC%20Options">RS/6000 and PowerPC Options</a>, for more information on whether long
calls are necessary.

     <br><dt><code>long_call/short_call</code>
     <dd>This attribute specifies how a particular function is called on
ARM.  Both attributes override the <code>-mlong-calls</code> (see <a href="ARM-Options.html#ARM%20Options">ARM Options</a>)
command line switch and <code>#pragma long_calls</code> settings.  The
<code>long_call</code> attribute causes the compiler to always call the
function by first loading its address into a register and then using the
contents of that register.   The <code>short_call</code> attribute always places
the offset to the function from the call site into the <code>BL</code>
instruction directly.

     <br><dt><code>function_vector</code>
     <dd>Use this attribute on the H8/300, H8/300H, and H8S to indicate that the specified
function should be called through the function vector.  Calling a
function through the function vector will reduce code size, however;
the function vector has a limited size (maximum 128 entries on the H8/300
and 64 entries on the H8/300H and H8S) and shares space with the interrupt vector.

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

     <br><dt><code>interrupt</code>
     <dd>Use this attribute on the ARM, AVR, C4x, M32R/D and Xstormy16 ports to indicate
that the specified function is an interrupt handler.  The compiler will
generate function entry and exit sequences suitable for use in an
interrupt handler when this attribute is present.

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

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

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

     <pre class="smallexample">          void f () __attribute__ ((interrupt ("IRQ")));
          </pre>

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

     <br><dt><code>interrupt_handler</code>
     <dd>Use this attribute on the m68k, H8/300, H8/300H, H8S, and SH to indicate that
the specified function is an interrupt handler.  The compiler will generate
function entry and exit sequences suitable for use in an interrupt
handler when this attribute is present.

     <br><dt><code>sp_switch</code>
     <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.

     <pre class="smallexample">          void *alt_stack;
          void f () __attribute__ ((interrupt_handler,
                                    sp_switch ("alt_stack")));
          </pre>

     <br><dt><code>trap_exit</code>
     <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.

     <br><dt><code>eightbit_data</code>
     <dd>Use this attribute on the H8/300, H8/300H, and H8S to indicate that the specified
variable should be placed into the eight bit data section. 
The compiler will generate more efficient code for certain operations
on data in the eight bit data area.  Note the eight bit data area is limited to
256 bytes of data.

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

     <br><dt><code>tiny_data</code>
     <dd>Use this attribute on the H8/300H and H8S to indicate that the specified
variable should be placed into the tiny data section. 
The compiler will generate more efficient code for loads and stores
on data in the tiny data section.  Note the tiny data area is limited to
slightly under 32kbytes of data.

     <br><dt><code>saveall</code>
     <dd>Use this attribute on the H8/300, H8/300H, and H8S to indicate that
all registers except the stack pointer should be saved in the prologue
regardless of whether they are used or not.

     <br><dt><code>signal</code>
     <dd>Use this attribute on the AVR to indicate that the specified
function is a signal handler.  The compiler will generate function
entry and exit sequences suitable for use in a signal handler when this
attribute is present.  Interrupts will be disabled inside the function.

     <br><dt><code>naked</code>
     <dd>Use this attribute on the ARM, AVR, C4x and IP2K ports to indicate that the
specified function does not need prologue/epilogue sequences generated by
the compiler.  It is up to the programmer to provide these sequences.

     <br><dt><code>model (</code><var>model-name</var><code>)</code>
     <dd>

     <p>On the M32R/D, use this attribute to set the addressability of an
object, and of the code generated for a function.  The identifier
<var>model-name</var> is one of <code>small</code>, <code>medium</code>, or
<code>large</code>, representing each of the code models.

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

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

     <p>Large model objects may live anywhere in the 32-bit address space (the
compiler 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).

     <p>On IA-64, use this attribute to set the addressability of an object. 
At present, the only supported identifier for <var>model-name</var> 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.

     <br><dt><code>far</code>
     <dd>On 68HC11 and 68HC12 the <code>far</code> attribute causes the compiler to
use a calling convention that takes care of switching memory banks when
entering and leaving a function.  This calling convention is also the
default when using the <code>-mlong-calls</code> option.

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

     <p>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>.

     <br><dt><code>near</code>
     <dd>On 68HC11 and 68HC12 the <code>near</code> attribute causes the compiler to
use the normal calling convention based on <code>jsr</code> and <code>rts</code>. 
This attribute can be used to cancel the effect of the <code>-mlong-calls</code>
option.

     <br><dt><code>dllimport</code>
     <dd>On Microsoft Windows targets, the <code>dllimport</code> attribute causes the compiler
to reference a function or variable via a global pointer to a pointer
that is set up by the Microsoft Windows dll library. The pointer name is formed by
combining <code>_imp__</code> and the function or variable name. The attribute
implies <code>extern</code> storage.

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

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

     <p>On cygwin, mingw and arm-pe targets, <code>__declspec(dllimport)</code> is
recognized as a synonym for <code>__attribute__ ((dllimport))</code> for
compatibility with other Microsoft Windows compilers.

     <p>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 GNU ld, but can now be avoided by passing
the <code>--enable-auto-import</code> switch to ld. As with functions, using
the attribute for a variable eliminates a thunk in the dll.

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

     <br><dt><code>dllexport</code>
     <dd>On Microsoft Windows targets the <code>dllexport</code> attribute causes the compiler to
provide a global pointer to a pointer in a dll, so that it can be
referenced with the <code>dllimport</code> attribute. The pointer name is
formed by combining <code>_imp__</code> and the function or variable name.

     <p>Currently, the <code>dllexport</code>attribute is ignored for inlined
functions, but export can be forced by using the
<code>-fkeep-inline-functions</code> flag. The attribute is also ignored for
undefined symbols.

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

     <p>On cygwin, mingw and arm-pe targets, <code>__declspec(dllexport)</code> is
recognized as a synonym for <code>__attribute__ ((dllexport))</code> for
compatibility with other Microsoft Windows compilers.

     <p>Alternative methods for including the symbol in the dll's export table
are to use a .def file with an <code>EXPORTS</code> section or, with GNU ld,
using the <code>--export-all</code> linker flag.

   </dl>

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

   <p>Some people object to the <code>__attribute__</code> feature, suggesting that
ISO C's <code>#pragma</code> should be used instead.  At the time
<code>__attribute__</code> was designed, there were two reasons for not doing
this.

     <ol type=1 start=1>
<li>It is impossible to generate <code>#pragma</code> commands from a macro.

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

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

   <p>The ISO C99 standard includes <code>_Pragma</code>, which now allows pragmas
to be generated from macros.  In addition, a <code>#pragma GCC</code>
namespace is now in use for GCC-specific pragmas.  However, it has been
found convenient to use <code>__attribute__</code> to achieve a natural
attachment of attributes to their corresponding declarations, whereas
<code>#pragma GCC</code> is of use for constructs that do not naturally form
part of the grammar.  See <a href="../cpp/Other-Directives.html#Other%20Directives">Miscellaneous Preprocessing Directives</a>.

   </body></html>