function-attributes.html

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

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

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

     <p>The <code>format-arg</code> attribute allows you to identify your own
functions which modify format strings, so that GCC can check the
calls to <code>printf</code>, <code>scanf</code>, <code>strftime</code> or <code>strfmon</code>
type function whose operands are a call to one of your own function. 
The compiler always treats <code>gettext</code>, <code>dgettext</code>, and
<code>dcgettext</code> in this manner except when strict ISO C support is
requested by <code>-ansi</code> or an appropriate <code>-std</code> option, or
<code>-ffreestanding</code> is used.  See <a href="C-Dialect-Options.html#C%20Dialect%20Options">Options Controlling C Dialect</a>.

     <br><dt><code>nonnull (</code><var>arg-index</var><code>, ...)</code>
     <dd>The <code>nonnull</code> attribute specifies that some function parameters should
be non-null pointers.  For instance, the declaration:

     <pre class="smallexample">          extern void *
          my_memcpy (void *dest, const void *src, size_t len)
          	__attribute__((nonnull (1, 2)));
          </pre>

     <p>causes the compiler to check that, in calls to <code>my_memcpy</code>,
arguments <var>dest</var> and <var>src</var> are non-null.  If the compiler
determines that a null pointer is passed in an argument slot marked
as non-null, and the <code>-Wnonnull</code> 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.

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

     <pre class="smallexample">          extern void *
          my_memcpy (void *dest, const void *src, size_t len)
          	__attribute__((nonnull));
          </pre>

     <br><dt><code>no_instrument_function</code>
     <dd>If <code>-finstrument-functions</code> is given, profiling function calls will
be generated at entry and exit of most user-compiled functions. 
Functions with this attribute will not be so instrumented.

     <br><dt><code>section ("</code><var>section-name</var><code>")</code>
     <dd>Normally, the compiler places the code it generates in the <code>text</code> section. 
Sometimes, however, you need additional sections, or you need certain
particular functions to appear in special sections.  The <code>section</code>
attribute specifies that a function lives in a particular section. 
For example, the declaration:

     <pre class="smallexample">          extern void foobar (void) __attribute__ ((section ("bar")));
          </pre>

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

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

     <br><dt><code>constructor</code>
     <dd><dt><code>destructor</code>
     <dd>The <code>constructor</code> attribute causes the function to be called
automatically before execution enters <code>main ()</code>.  Similarly, the
<code>destructor</code> attribute causes the function to be called
automatically after <code>main ()</code> has completed or <code>exit ()</code> has
been called.  Functions with these attributes are useful for
initializing data that will be used implicitly during the execution of
the program.

     <p>These attributes are not currently implemented for Objective-C.

     <br><dt><code>unused</code>
     <dd>This attribute, attached to a function, means that the function is meant
to be possibly unused.  GCC will not produce a warning for this
function.

     <br><dt><code>used</code>
     <dd>This attribute, attached to a function, means that code must be emitted
for the function even if it appears that the function is not referenced. 
This is useful, for example, when the function is referenced only in
inline assembly.

     <br><dt><code>deprecated</code>
     <dd>The <code>deprecated</code> attribute results in a warning if the function
is used anywhere in the source file.  This is useful when identifying
functions that are expected to be removed in a future version of a
program.  The warning also includes the location of the declaration
of the deprecated function, to enable users to easily find further
information about why the function is deprecated, or what they should
do instead.  Note that the warnings only occurs for uses:

     <pre class="smallexample">          int old_fn () __attribute__ ((deprecated));
          int old_fn ();
          int (*fn_ptr)() = old_fn;
          </pre>

     <p>results in a warning on line 3 but not line 2.

     <p>The <code>deprecated</code> attribute can also be used for variables and
types (see <a href="Variable-Attributes.html#Variable%20Attributes">Variable Attributes</a>, see <a href="Type-Attributes.html#Type%20Attributes">Type Attributes</a>.)

     <br><dt><code>warn_unused_result</code>
     <dd>The <code>warn_unused_result</code> attribute causes a warning to be emitted
if a caller of the function with this attribute does not use its
return value.  This is useful for functions where not checking
the result is either a security problem or always a bug, such as
<code>realloc</code>.

     <pre class="smallexample">          int fn () __attribute__ ((warn_unused_result));
          int foo ()
          {
            if (fn () &lt; 0) return -1;
            fn ();
            return 0;
          }
          </pre>

     <p>results in warning on line 5.

     <br><dt><code>weak</code>
     <dd>The <code>weak</code> attribute causes the declaration to be emitted as a weak
symbol rather than a global.  This is primarily useful in defining
library functions which can be overridden in user code, though it can
also be used with non-function declarations.  Weak symbols are supported
for ELF targets, and also for a.out targets when using the GNU assembler
and linker.

     <br><dt><code>malloc</code>
     <dd>The <code>malloc</code> attribute is used to tell the compiler that a function
may be treated as if any non-<code>NULL</code> pointer it returns cannot
alias any other pointer valid when the function returns. 
This will often improve optimization. 
Standard functions with this property include <code>malloc</code> and
<code>calloc</code>.  <code>realloc</code>-like functions have this property as
long as the old pointer is never referred to (including comparing it
to the new pointer) after the function returns a non-<code>NULL</code>
value.

     <br><dt><code>alias ("</code><var>target</var><code>")</code>
     <dd>The <code>alias</code> attribute causes the declaration to be emitted as an
alias for another symbol, which must be specified.  For instance,

     <pre class="smallexample">          void __f () { /* Do something. */; }
          void f () __attribute__ ((weak, alias ("__f")));
          </pre>

     <p>declares <code>f</code> to be a weak alias for <code>__f</code>.  In C++, the
mangled name for the target must be used.

     <p>Not all target machines support this attribute.

     <br><dt><code>visibility ("</code><var>visibility_type</var><code>")</code>
     <dd>The <code>visibility</code> attribute on ELF targets causes the declaration
to be emitted with default, hidden, protected or internal visibility.

     <pre class="smallexample">          void __attribute__ ((visibility ("protected")))
          f () { /* Do something. */; }
          int i __attribute__ ((visibility ("hidden")));
          </pre>

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

          <dl>
<dt><dfn>default</dfn>
          <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.

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

          <br><dt><dfn>protected</dfn>
          <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.

          <br><dt><dfn>internal</dfn>
          <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 <em>never</em>
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. 
</dl>

     <p>Not all ELF targets support this attribute.

     <br><dt><code>regparm (</code><var>number</var><code>)</code>
     <dd>On the Intel 386, the <code>regparm</code> attribute causes the compiler to
pass up to <var>number</var> integer arguments in registers EAX,
EDX, and ECX instead of on the stack.  Functions that take a
variable number of arguments will continue to be passed all of their
arguments on the stack.

     <p>Beware that on some ELF systems this attribute is unsuitable for
global functions in shared libraries with lazy binding (which is the
default).  Lazy binding 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.)

     <br><dt><code>stdcall</code>
     <dd>On the Intel 386, the <code>stdcall</code> attribute causes the compiler to
assume that the called function will pop off the stack space used to
pass arguments, unless it takes a variable number of arguments.

     <br><dt><code>fastcall</code>
     <dd>On the Intel 386, the <code>fastcall</code> attribute causes the compiler to
pass the first two arguments in the registers ECX and EDX. Subsequent
arguments are passed on the stack. The called function will pop the
arguments off the stack. If the number of arguments is variable all
arguments are pushed on the stack.

     <br><dt><code>cdecl</code>
     <dd>On the Intel 386, the <code>cdecl</code> attribute causes the compiler to
assume that the calling function will pop off the stack space used to
pass arguments.  This is
useful to override the effects of the <code>-mrtd</code> switch.

     <br><dt><code>longcall/shortcall</code>
     <dd>On the RS/6000 and PowerPC, the <code>longcall</code> attribute causes the
compiler to always call this function via a pointer, just as it would if
the <code>-mlongcall</code> option had been specified.  The <code>shortcall</code>
attribute causes the compiler not to do this.  These attributes override