You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
1366 lines
64 KiB
HTML
1366 lines
64 KiB
HTML
4 years ago
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
||
|
|
<html>
|
||
|
|
<!-- Copyright (C) 1988-2018 Free Software Foundation, Inc.
|
||
|
|
|
||
|
|
Permission is granted to copy, distribute and/or modify this document
|
||
|
|
under the terms of the GNU Free Documentation License, Version 1.3 or
|
||
|
|
any later version published by the Free Software Foundation; with the
|
||
|
|
Invariant Sections being "Funding Free Software", the Front-Cover
|
||
|
|
Texts being (a) (see below), and with the Back-Cover Texts being (b)
|
||
|
|
(see below). A copy of the license is included in the section entitled
|
||
|
|
"GNU Free Documentation License".
|
||
|
|
|
||
|
|
(a) The FSF's Front-Cover Text is:
|
||
|
|
|
||
|
|
A GNU Manual
|
||
|
|
|
||
|
|
(b) The FSF's Back-Cover Text is:
|
||
|
|
|
||
|
|
You have freedom to copy and modify this GNU Manual, like GNU
|
||
|
|
software. Copies published by the Free Software Foundation raise
|
||
|
|
funds for GNU development. -->
|
||
|
|
<!-- Created by GNU Texinfo 6.4, http://www.gnu.org/software/texinfo/ -->
|
||
|
|
<head>
|
||
|
|
<title>Common Function Attributes (Using the GNU Compiler Collection (GCC))</title>
|
||
|
|
|
||
|
|
<meta name="description" content="Common Function Attributes (Using the GNU Compiler Collection (GCC))">
|
||
|
|
<meta name="keywords" content="Common Function Attributes (Using the GNU Compiler Collection (GCC))">
|
||
|
|
<meta name="resource-type" content="document">
|
||
|
|
<meta name="distribution" content="global">
|
||
|
|
<meta name="Generator" content="makeinfo">
|
||
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
||
|
|
<link href="index.html#Top" rel="start" title="Top">
|
||
|
|
<link href="Option-Index.html#Option-Index" rel="index" title="Option Index">
|
||
|
|
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
|
||
|
|
<link href="Function-Attributes.html#Function-Attributes" rel="up" title="Function Attributes">
|
||
|
|
<link href="AArch64-Function-Attributes.html#AArch64-Function-Attributes" rel="next" title="AArch64 Function Attributes">
|
||
|
|
<link href="Function-Attributes.html#Function-Attributes" rel="prev" title="Function Attributes">
|
||
|
|
<style type="text/css">
|
||
|
|
<!--
|
||
|
|
a.summary-letter {text-decoration: none}
|
||
|
|
blockquote.indentedblock {margin-right: 0em}
|
||
|
|
blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
|
||
|
|
blockquote.smallquotation {font-size: smaller}
|
||
|
|
div.display {margin-left: 3.2em}
|
||
|
|
div.example {margin-left: 3.2em}
|
||
|
|
div.lisp {margin-left: 3.2em}
|
||
|
|
div.smalldisplay {margin-left: 3.2em}
|
||
|
|
div.smallexample {margin-left: 3.2em}
|
||
|
|
div.smalllisp {margin-left: 3.2em}
|
||
|
|
kbd {font-style: oblique}
|
||
|
|
pre.display {font-family: inherit}
|
||
|
|
pre.format {font-family: inherit}
|
||
|
|
pre.menu-comment {font-family: serif}
|
||
|
|
pre.menu-preformatted {font-family: serif}
|
||
|
|
pre.smalldisplay {font-family: inherit; font-size: smaller}
|
||
|
|
pre.smallexample {font-size: smaller}
|
||
|
|
pre.smallformat {font-family: inherit; font-size: smaller}
|
||
|
|
pre.smalllisp {font-size: smaller}
|
||
|
|
span.nolinebreak {white-space: nowrap}
|
||
|
|
span.roman {font-family: initial; font-weight: normal}
|
||
|
|
span.sansserif {font-family: sans-serif; font-weight: normal}
|
||
|
|
ul.no-bullet {list-style: none}
|
||
|
|
-->
|
||
|
|
</style>
|
||
|
|
|
||
|
|
|
||
|
|
</head>
|
||
|
|
|
||
|
|
<body lang="en">
|
||
|
|
<a name="Common-Function-Attributes"></a>
|
||
|
|
<div class="header">
|
||
|
|
<p>
|
||
|
|
Next: <a href="AArch64-Function-Attributes.html#AArch64-Function-Attributes" accesskey="n" rel="next">AArch64 Function Attributes</a>, Up: <a href="Function-Attributes.html#Function-Attributes" accesskey="u" rel="up">Function Attributes</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Option-Index.html#Option-Index" title="Index" rel="index">Index</a>]</p>
|
||
|
|
</div>
|
||
|
|
<hr>
|
||
|
|
<a name="Common-Function-Attributes-1"></a>
|
||
|
|
<h4 class="subsection">6.31.1 Common Function Attributes</h4>
|
||
|
|
|
||
|
|
<p>The following attributes are supported on most targets.
|
||
|
|
</p>
|
||
|
|
<dl compact="compact">
|
||
|
|
<dt><code>alias ("<var>target</var>")</code></dt>
|
||
|
|
<dd><a name="index-alias-function-attribute"></a>
|
||
|
|
<p>The <code>alias</code> attribute causes the declaration to be emitted as an
|
||
|
|
alias for another symbol, which must be specified. For instance,
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample">void __f () { /* <span class="roman">Do something.</span> */; }
|
||
|
|
void f () __attribute__ ((weak, alias ("__f")));
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>defines ‘<samp>f</samp>’ to be a weak alias for ‘<samp>__f</samp>’. In C++, the
|
||
|
|
mangled name for the target must be used. It is an error if ‘<samp>__f</samp>’
|
||
|
|
is not defined in the same translation unit.
|
||
|
|
</p>
|
||
|
|
<p>This attribute requires assembler and object file support,
|
||
|
|
and may not be available on all targets.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>aligned (<var>alignment</var>)</code></dt>
|
||
|
|
<dd><a name="index-aligned-function-attribute"></a>
|
||
|
|
<p>This attribute specifies a minimum alignment for the function,
|
||
|
|
measured in bytes.
|
||
|
|
</p>
|
||
|
|
<p>You cannot use this attribute to decrease the alignment of a function,
|
||
|
|
only to increase it. However, when you explicitly specify a function
|
||
|
|
alignment this overrides the effect of the
|
||
|
|
<samp>-falign-functions</samp> (see <a href="Optimize-Options.html#Optimize-Options">Optimize Options</a>) option for this
|
||
|
|
function.
|
||
|
|
</p>
|
||
|
|
<p>Note that the effectiveness of <code>aligned</code> attributes may be
|
||
|
|
limited by inherent limitations in your linker. On many systems, the
|
||
|
|
linker is only able to arrange for functions to be aligned up to a
|
||
|
|
certain maximum alignment. (For some linkers, the maximum supported
|
||
|
|
alignment may be very very small.) See your linker documentation for
|
||
|
|
further information.
|
||
|
|
</p>
|
||
|
|
<p>The <code>aligned</code> attribute can also be used for variables and fields
|
||
|
|
(see <a href="Variable-Attributes.html#Variable-Attributes">Variable Attributes</a>.)
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>alloc_align</code></dt>
|
||
|
|
<dd><a name="index-alloc_005falign-function-attribute"></a>
|
||
|
|
<p>The <code>alloc_align</code> attribute is used to tell the compiler that the
|
||
|
|
function return value points to memory, where the returned pointer minimum
|
||
|
|
alignment is given by one of the functions parameters. GCC uses this
|
||
|
|
information to improve pointer alignment analysis.
|
||
|
|
</p>
|
||
|
|
<p>The function parameter denoting the allocated alignment is specified by
|
||
|
|
one integer argument, whose number is the argument of the attribute.
|
||
|
|
Argument numbering starts at one.
|
||
|
|
</p>
|
||
|
|
<p>For instance,
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample">void* my_memalign(size_t, size_t) __attribute__((alloc_align(1)))
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>declares that <code>my_memalign</code> returns memory with minimum alignment
|
||
|
|
given by parameter 1.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>alloc_size</code></dt>
|
||
|
|
<dd><a name="index-alloc_005fsize-function-attribute"></a>
|
||
|
|
<p>The <code>alloc_size</code> attribute is used to tell the compiler that the
|
||
|
|
function return value points to memory, where the size is given by
|
||
|
|
one or two of the functions parameters. GCC uses this
|
||
|
|
information to improve the correctness of <code>__builtin_object_size</code>.
|
||
|
|
</p>
|
||
|
|
<p>The function parameter(s) denoting the allocated size are specified by
|
||
|
|
one or two integer arguments supplied to the attribute. The allocated size
|
||
|
|
is either the value of the single function argument specified or the product
|
||
|
|
of the two function arguments specified. Argument numbering starts at
|
||
|
|
one.
|
||
|
|
</p>
|
||
|
|
<p>For instance,
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample">void* my_calloc(size_t, size_t) __attribute__((alloc_size(1,2)))
|
||
|
|
void* my_realloc(void*, size_t) __attribute__((alloc_size(2)))
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>declares that <code>my_calloc</code> returns memory of the size given by
|
||
|
|
the product of parameter 1 and 2 and that <code>my_realloc</code> returns memory
|
||
|
|
of the size given by parameter 2.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>always_inline</code></dt>
|
||
|
|
<dd><a name="index-always_005finline-function-attribute"></a>
|
||
|
|
<p>Generally, functions are not inlined unless optimization is specified.
|
||
|
|
For functions declared inline, this attribute inlines the function
|
||
|
|
independent of any restrictions that otherwise apply to inlining.
|
||
|
|
Failure to inline such a function is diagnosed as an error.
|
||
|
|
Note that if such a function is called indirectly the compiler may
|
||
|
|
or may not inline it depending on optimization level and a failure
|
||
|
|
to inline an indirect call may or may not be diagnosed.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>artificial</code></dt>
|
||
|
|
<dd><a name="index-artificial-function-attribute"></a>
|
||
|
|
<p>This attribute is useful for small inline wrappers that if possible
|
||
|
|
should appear during debugging as a unit. Depending on the debug
|
||
|
|
info format it either means marking the function as artificial
|
||
|
|
or using the caller location for all instructions within the inlined
|
||
|
|
body.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>assume_aligned</code></dt>
|
||
|
|
<dd><a name="index-assume_005faligned-function-attribute"></a>
|
||
|
|
<p>The <code>assume_aligned</code> attribute is used to tell the compiler that the
|
||
|
|
function return value points to memory, where the returned pointer minimum
|
||
|
|
alignment is given by the first argument.
|
||
|
|
If the attribute has two arguments, the second argument is misalignment offset.
|
||
|
|
</p>
|
||
|
|
<p>For instance
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample">void* my_alloc1(size_t) __attribute__((assume_aligned(16)))
|
||
|
|
void* my_alloc2(size_t) __attribute__((assume_aligned(32, 8)))
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>declares that <code>my_alloc1</code> returns 16-byte aligned pointer and
|
||
|
|
that <code>my_alloc2</code> returns a pointer whose value modulo 32 is equal
|
||
|
|
to 8.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>bnd_instrument</code></dt>
|
||
|
|
<dd><a name="index-bnd_005finstrument-function-attribute"></a>
|
||
|
|
<p>The <code>bnd_instrument</code> attribute on functions is used to inform the
|
||
|
|
compiler that the function should be instrumented when compiled
|
||
|
|
with the <samp>-fchkp-instrument-marked-only</samp> option.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>bnd_legacy</code></dt>
|
||
|
|
<dd><a name="index-bnd_005flegacy-function-attribute"></a>
|
||
|
|
<a name="index-Pointer-Bounds-Checker-attributes"></a>
|
||
|
|
<p>The <code>bnd_legacy</code> attribute on functions is used to inform the
|
||
|
|
compiler that the function should not be instrumented when compiled
|
||
|
|
with the <samp>-fcheck-pointer-bounds</samp> option.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>cold</code></dt>
|
||
|
|
<dd><a name="index-cold-function-attribute"></a>
|
||
|
|
<p>The <code>cold</code> attribute on functions is used to inform the compiler that
|
||
|
|
the function is unlikely to be executed. The function is optimized for
|
||
|
|
size rather than speed and on many targets it is placed into a special
|
||
|
|
subsection of the text section so all cold functions appear close together,
|
||
|
|
improving code locality of non-cold parts of program. The paths leading
|
||
|
|
to calls of cold functions within code are marked as unlikely by the branch
|
||
|
|
prediction mechanism. It is thus useful to mark functions used to handle
|
||
|
|
unlikely conditions, such as <code>perror</code>, as cold to improve optimization
|
||
|
|
of hot functions that do call marked functions in rare occasions.
|
||
|
|
</p>
|
||
|
|
<p>When profile feedback is available, via <samp>-fprofile-use</samp>, cold functions
|
||
|
|
are automatically detected and this attribute is ignored.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>const</code></dt>
|
||
|
|
<dd><a name="index-const-function-attribute"></a>
|
||
|
|
<a name="index-functions-that-have-no-side-effects"></a>
|
||
|
|
<p>Many functions do not examine any values except their arguments, and
|
||
|
|
have no effects except to return a value. Calls to such functions lend
|
||
|
|
themselves to optimization such as common subexpression elimination.
|
||
|
|
The <code>const</code> attribute imposes greater restrictions on a function’s
|
||
|
|
definition than the similar <code>pure</code> attribute below because it prohibits
|
||
|
|
the function from reading global variables. Consequently, the presence of
|
||
|
|
the attribute on a function declaration allows GCC to emit more efficient
|
||
|
|
code for some calls to the function. Decorating the same function with
|
||
|
|
both the <code>const</code> and the <code>pure</code> attribute is diagnosed.
|
||
|
|
</p>
|
||
|
|
<a name="index-pointer-arguments"></a>
|
||
|
|
<p>Note that a function that has pointer arguments and examines the data
|
||
|
|
pointed to must <em>not</em> be declared <code>const</code>. Likewise, a
|
||
|
|
function that calls a non-<code>const</code> function usually must not be
|
||
|
|
<code>const</code>. Because a <code>const</code> function cannot have any side
|
||
|
|
effects it does not make sense for such a function to return <code>void</code>.
|
||
|
|
Declaring such a function is diagnosed.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>constructor</code></dt>
|
||
|
|
<dt><code>destructor</code></dt>
|
||
|
|
<dt><code>constructor (<var>priority</var>)</code></dt>
|
||
|
|
<dt><code>destructor (<var>priority</var>)</code></dt>
|
||
|
|
<dd><a name="index-constructor-function-attribute"></a>
|
||
|
|
<a name="index-destructor-function-attribute"></a>
|
||
|
|
<p>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> completes or <code>exit ()</code> is
|
||
|
|
called. Functions with these attributes are useful for
|
||
|
|
initializing data that is used implicitly during the execution of
|
||
|
|
the program.
|
||
|
|
</p>
|
||
|
|
<p>You may provide an optional integer priority to control the order in
|
||
|
|
which constructor and destructor functions are run. A constructor
|
||
|
|
with a smaller priority number runs before a constructor with a larger
|
||
|
|
priority number; the opposite relationship holds for destructors. So,
|
||
|
|
if you have a constructor that allocates a resource and a destructor
|
||
|
|
that deallocates the same resource, both functions typically have the
|
||
|
|
same priority. The priorities for constructor and destructor
|
||
|
|
functions are the same as those specified for namespace-scope C++
|
||
|
|
objects (see <a href="C_002b_002b-Attributes.html#C_002b_002b-Attributes">C++ Attributes</a>). However, at present, the order in which
|
||
|
|
constructors for C++ objects with static storage duration and functions
|
||
|
|
decorated with attribute <code>constructor</code> are invoked is unspecified.
|
||
|
|
In mixed declarations, attribute <code>init_priority</code> can be used to
|
||
|
|
impose a specific ordering.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>deprecated</code></dt>
|
||
|
|
<dt><code>deprecated (<var>msg</var>)</code></dt>
|
||
|
|
<dd><a name="index-deprecated-function-attribute"></a>
|
||
|
|
<p>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:
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample">int old_fn () __attribute__ ((deprecated));
|
||
|
|
int old_fn ();
|
||
|
|
int (*fn_ptr)() = old_fn;
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>results in a warning on line 3 but not line 2. The optional <var>msg</var>
|
||
|
|
argument, which must be a string, is printed in the warning if
|
||
|
|
present.
|
||
|
|
</p>
|
||
|
|
<p>The <code>deprecated</code> attribute can also be used for variables and
|
||
|
|
types (see <a href="Variable-Attributes.html#Variable-Attributes">Variable Attributes</a>, see <a href="Type-Attributes.html#Type-Attributes">Type Attributes</a>.)
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>error ("<var>message</var>")</code></dt>
|
||
|
|
<dt><code>warning ("<var>message</var>")</code></dt>
|
||
|
|
<dd><a name="index-error-function-attribute"></a>
|
||
|
|
<a name="index-warning-function-attribute"></a>
|
||
|
|
<p>If the <code>error</code> or <code>warning</code> attribute
|
||
|
|
is used on a function declaration and a call to such a function
|
||
|
|
is not eliminated through dead code elimination or other optimizations,
|
||
|
|
an error or warning (respectively) that includes <var>message</var> is diagnosed.
|
||
|
|
This is useful
|
||
|
|
for compile-time checking, especially together with <code>__builtin_constant_p</code>
|
||
|
|
and inline functions where checking the inline function arguments is not
|
||
|
|
possible through <code>extern char [(condition) ? 1 : -1];</code> tricks.
|
||
|
|
</p>
|
||
|
|
<p>While it is possible to leave the function undefined and thus invoke
|
||
|
|
a link failure (to define the function with
|
||
|
|
a message in <code>.gnu.warning*</code> section),
|
||
|
|
when using these attributes the problem is diagnosed
|
||
|
|
earlier and with exact location of the call even in presence of inline
|
||
|
|
functions or when not emitting debugging information.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>externally_visible</code></dt>
|
||
|
|
<dd><a name="index-externally_005fvisible-function-attribute"></a>
|
||
|
|
<p>This attribute, attached to a global variable or function, nullifies
|
||
|
|
the effect of the <samp>-fwhole-program</samp> command-line option, so the
|
||
|
|
object remains visible outside the current compilation unit.
|
||
|
|
</p>
|
||
|
|
<p>If <samp>-fwhole-program</samp> is used together with <samp>-flto</samp> and
|
||
|
|
<code>gold</code> is used as the linker plugin,
|
||
|
|
<code>externally_visible</code> attributes are automatically added to functions
|
||
|
|
(not variable yet due to a current <code>gold</code> issue)
|
||
|
|
that are accessed outside of LTO objects according to resolution file
|
||
|
|
produced by <code>gold</code>.
|
||
|
|
For other linkers that cannot generate resolution file,
|
||
|
|
explicit <code>externally_visible</code> attributes are still necessary.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>flatten</code></dt>
|
||
|
|
<dd><a name="index-flatten-function-attribute"></a>
|
||
|
|
<p>Generally, inlining into a function is limited. For a function marked with
|
||
|
|
this attribute, every call inside this function is inlined, if possible.
|
||
|
|
Whether the function itself is considered for inlining depends on its size and
|
||
|
|
the current inlining parameters.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>format (<var>archetype</var>, <var>string-index</var>, <var>first-to-check</var>)</code></dt>
|
||
|
|
<dd><a name="index-format-function-attribute"></a>
|
||
|
|
<a name="index-functions-with-printf_002c-scanf_002c-strftime-or-strfmon-style-arguments"></a>
|
||
|
|
<a name="index-Wformat-3"></a>
|
||
|
|
<p>The <code>format</code> attribute specifies that a function takes <code>printf</code>,
|
||
|
|
<code>scanf</code>, <code>strftime</code> or <code>strfmon</code> style arguments that
|
||
|
|
should be type-checked against a format string. For example, the
|
||
|
|
declaration:
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample">extern int
|
||
|
|
my_printf (void *my_object, const char *my_format, ...)
|
||
|
|
__attribute__ ((format (printf, 2, 3)));
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>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>.
|
||
|
|
</p>
|
||
|
|
<p>The parameter <var>archetype</var> determines how the format string is
|
||
|
|
interpreted, and should be <code>printf</code>, <code>scanf</code>, <code>strftime</code>,
|
||
|
|
<code>gnu_printf</code>, <code>gnu_scanf</code>, <code>gnu_strftime</code> or
|
||
|
|
<code>strfmon</code>. (You can also use <code>__printf__</code>,
|
||
|
|
<code>__scanf__</code>, <code>__strftime__</code> or <code>__strfmon__</code>.) On
|
||
|
|
MinGW targets, <code>ms_printf</code>, <code>ms_scanf</code>, and
|
||
|
|
<code>ms_strftime</code> are also present.
|
||
|
|
<var>archetype</var> values such as <code>printf</code> refer to the formats accepted
|
||
|
|
by the system’s C runtime library,
|
||
|
|
while values prefixed with ‘<samp>gnu_</samp>’ always refer
|
||
|
|
to the formats accepted by the GNU C Library. On Microsoft Windows
|
||
|
|
targets, values prefixed with ‘<samp>ms_</samp>’ refer to the formats accepted by the
|
||
|
|
<samp>msvcrt.dll</samp> library.
|
||
|
|
The parameter <var>string-index</var>
|
||
|
|
specifies which argument is the format string argument (starting
|
||
|
|
from 1), while <var>first-to-check</var> 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 <var>string-index</var> and <var>first-to-check</var>.
|
||
|
|
</p>
|
||
|
|
<p>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.
|
||
|
|
</p>
|
||
|
|
<a name="index-ffreestanding-3"></a>
|
||
|
|
<a name="index-fno_002dbuiltin-2"></a>
|
||
|
|
<p>The <code>format</code> attribute allows you to identify your own functions
|
||
|
|
that take format strings as arguments, so that GCC can check the
|
||
|
|
calls to these functions for errors. The compiler always (unless
|
||
|
|
<samp>-ffreestanding</samp> or <samp>-fno-builtin</samp> is used) checks formats
|
||
|
|
for the standard library functions <code>printf</code>, <code>fprintf</code>,
|
||
|
|
<code>sprintf</code>, <code>scanf</code>, <code>fscanf</code>, <code>sscanf</code>, <code>strftime</code>,
|
||
|
|
<code>vprintf</code>, <code>vfprintf</code> and <code>vsprintf</code> whenever such
|
||
|
|
warnings are requested (using <samp>-Wformat</samp>), so there is no need to
|
||
|
|
modify the header file <samp>stdio.h</samp>. In C99 mode, the functions
|
||
|
|
<code>snprintf</code>, <code>vsnprintf</code>, <code>vscanf</code>, <code>vfscanf</code> and
|
||
|
|
<code>vsscanf</code> are also checked. Except in strictly conforming C
|
||
|
|
standard modes, the X/Open function <code>strfmon</code> is also checked as
|
||
|
|
are <code>printf_unlocked</code> and <code>fprintf_unlocked</code>.
|
||
|
|
See <a href="C-Dialect-Options.html#C-Dialect-Options">Options Controlling C Dialect</a>.
|
||
|
|
</p>
|
||
|
|
<p>For Objective-C dialects, <code>NSString</code> (or <code>__NSString__</code>) is
|
||
|
|
recognized in the same context. Declarations including these format attributes
|
||
|
|
are parsed for correct syntax, however the result of checking of such format
|
||
|
|
strings is not yet defined, and is not carried out by this version of the
|
||
|
|
compiler.
|
||
|
|
</p>
|
||
|
|
<p>The target may also provide additional types of format checks.
|
||
|
|
See <a href="Target-Format-Checks.html#Target-Format-Checks">Format Checks Specific to Particular
|
||
|
|
Target Machines</a>.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>format_arg (<var>string-index</var>)</code></dt>
|
||
|
|
<dd><a name="index-format_005farg-function-attribute"></a>
|
||
|
|
<a name="index-Wformat_002dnonliteral-1"></a>
|
||
|
|
<p>The <code>format_arg</code> attribute specifies that a function takes a format
|
||
|
|
string for a <code>printf</code>, <code>scanf</code>, <code>strftime</code> or
|
||
|
|
<code>strfmon</code> style function and modifies it (for example, to translate
|
||
|
|
it into another language), so the result can be passed to a
|
||
|
|
<code>printf</code>, <code>scanf</code>, <code>strftime</code> or <code>strfmon</code> style
|
||
|
|
function (with the remaining arguments to the format function the same
|
||
|
|
as they would have been for the unmodified string). For example, the
|
||
|
|
declaration:
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample">extern char *
|
||
|
|
my_dgettext (char *my_domain, const char *my_format)
|
||
|
|
__attribute__ ((format_arg (2)));
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<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
|
||
|
|
<samp>-Wformat-nonliteral</samp> is used, but the calls could not be checked
|
||
|
|
without the attribute.
|
||
|
|
</p>
|
||
|
|
<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>
|
||
|
|
<p>The <code>format_arg</code> attribute allows you to identify your own
|
||
|
|
functions that 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 <samp>-ansi</samp> or an appropriate <samp>-std</samp> option, or
|
||
|
|
<samp>-ffreestanding</samp> or <samp>-fno-builtin</samp>
|
||
|
|
is used. See <a href="C-Dialect-Options.html#C-Dialect-Options">Options
|
||
|
|
Controlling C Dialect</a>.
|
||
|
|
</p>
|
||
|
|
<p>For Objective-C dialects, the <code>format-arg</code> attribute may refer to an
|
||
|
|
<code>NSString</code> reference for compatibility with the <code>format</code> attribute
|
||
|
|
above.
|
||
|
|
</p>
|
||
|
|
<p>The target may also allow additional types in <code>format-arg</code> attributes.
|
||
|
|
See <a href="Target-Format-Checks.html#Target-Format-Checks">Format Checks Specific to Particular
|
||
|
|
Target Machines</a>.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>gnu_inline</code></dt>
|
||
|
|
<dd><a name="index-gnu_005finline-function-attribute"></a>
|
||
|
|
<p>This attribute should be used with a function that is also declared
|
||
|
|
with the <code>inline</code> keyword. It directs GCC to treat the function
|
||
|
|
as if it were defined in gnu90 mode even when compiling in C99 or
|
||
|
|
gnu99 mode.
|
||
|
|
</p>
|
||
|
|
<p>If the function is declared <code>extern</code>, then this definition of the
|
||
|
|
function is used only for inlining. In no case is the function
|
||
|
|
compiled as a standalone function, not even if you take its address
|
||
|
|
explicitly. Such an address becomes an external reference, as if you
|
||
|
|
had only declared the function, and had not defined it. This has
|
||
|
|
almost the effect of a macro. The way to use this is to put a
|
||
|
|
function definition in a header file with this attribute, and put
|
||
|
|
another copy of the function, without <code>extern</code>, in a library
|
||
|
|
file. The definition in the header file causes most calls to the
|
||
|
|
function to be inlined. If any uses of the function remain, they
|
||
|
|
refer to the single copy in the library. Note that the two
|
||
|
|
definitions of the functions need not be precisely the same, although
|
||
|
|
if they do not have the same effect your program may behave oddly.
|
||
|
|
</p>
|
||
|
|
<p>In C, if the function is neither <code>extern</code> nor <code>static</code>, then
|
||
|
|
the function is compiled as a standalone function, as well as being
|
||
|
|
inlined where possible.
|
||
|
|
</p>
|
||
|
|
<p>This is how GCC traditionally handled functions declared
|
||
|
|
<code>inline</code>. Since ISO C99 specifies a different semantics for
|
||
|
|
<code>inline</code>, this function attribute is provided as a transition
|
||
|
|
measure and as a useful feature in its own right. This attribute is
|
||
|
|
available in GCC 4.1.3 and later. It is available if either of the
|
||
|
|
preprocessor macros <code>__GNUC_GNU_INLINE__</code> or
|
||
|
|
<code>__GNUC_STDC_INLINE__</code> are defined. See <a href="Inline.html#Inline">An Inline
|
||
|
|
Function is As Fast As a Macro</a>.
|
||
|
|
</p>
|
||
|
|
<p>In C++, this attribute does not depend on <code>extern</code> in any way,
|
||
|
|
but it still requires the <code>inline</code> keyword to enable its special
|
||
|
|
behavior.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>hot</code></dt>
|
||
|
|
<dd><a name="index-hot-function-attribute"></a>
|
||
|
|
<p>The <code>hot</code> attribute on a function is used to inform the compiler that
|
||
|
|
the function is a hot spot of the compiled program. The function is
|
||
|
|
optimized more aggressively and on many targets it is placed into a special
|
||
|
|
subsection of the text section so all hot functions appear close together,
|
||
|
|
improving locality.
|
||
|
|
</p>
|
||
|
|
<p>When profile feedback is available, via <samp>-fprofile-use</samp>, hot functions
|
||
|
|
are automatically detected and this attribute is ignored.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>ifunc ("<var>resolver</var>")</code></dt>
|
||
|
|
<dd><a name="index-ifunc-function-attribute"></a>
|
||
|
|
<a name="index-indirect-functions"></a>
|
||
|
|
<a name="index-functions-that-are-dynamically-resolved"></a>
|
||
|
|
<p>The <code>ifunc</code> attribute is used to mark a function as an indirect
|
||
|
|
function using the STT_GNU_IFUNC symbol type extension to the ELF
|
||
|
|
standard. This allows the resolution of the symbol value to be
|
||
|
|
determined dynamically at load time, and an optimized version of the
|
||
|
|
routine to be selected for the particular processor or other system
|
||
|
|
characteristics determined then. To use this attribute, first define
|
||
|
|
the implementation functions available, and a resolver function that
|
||
|
|
returns a pointer to the selected implementation function. The
|
||
|
|
implementation functions’ declarations must match the API of the
|
||
|
|
function being implemented. The resolver should be declared to
|
||
|
|
be a function taking no arguments and returning a pointer to
|
||
|
|
a function of the same type as the implementation. For example:
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample">void *my_memcpy (void *dst, const void *src, size_t len)
|
||
|
|
{
|
||
|
|
…
|
||
|
|
return dst;
|
||
|
|
}
|
||
|
|
|
||
|
|
static void * (*resolve_memcpy (void))(void *, const void *, size_t)
|
||
|
|
{
|
||
|
|
return my_memcpy; // we will just always select this routine
|
||
|
|
}
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>The exported header file declaring the function the user calls would
|
||
|
|
contain:
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample">extern void *memcpy (void *, const void *, size_t);
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>allowing the user to call <code>memcpy</code> as a regular function, unaware of
|
||
|
|
the actual implementation. Finally, the indirect function needs to be
|
||
|
|
defined in the same translation unit as the resolver function:
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample">void *memcpy (void *, const void *, size_t)
|
||
|
|
__attribute__ ((ifunc ("resolve_memcpy")));
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>In C++, the <code>ifunc</code> attribute takes a string that is the mangled name
|
||
|
|
of the resolver function. A C++ resolver for a non-static member function
|
||
|
|
of class <code>C</code> should be declared to return a pointer to a non-member
|
||
|
|
function taking pointer to <code>C</code> as the first argument, followed by
|
||
|
|
the same arguments as of the implementation function. G++ checks
|
||
|
|
the signatures of the two functions and issues
|
||
|
|
a <samp>-Wattribute-alias</samp> warning for mismatches. To suppress a warning
|
||
|
|
for the necessary cast from a pointer to the implementation member function
|
||
|
|
to the type of the corresponding non-member function use
|
||
|
|
the <samp>-Wno-pmf-conversions</samp> option. For example:
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample">class S
|
||
|
|
{
|
||
|
|
private:
|
||
|
|
int debug_impl (int);
|
||
|
|
int optimized_impl (int);
|
||
|
|
|
||
|
|
typedef int Func (S*, int);
|
||
|
|
|
||
|
|
static Func* resolver ();
|
||
|
|
public:
|
||
|
|
|
||
|
|
int interface (int);
|
||
|
|
};
|
||
|
|
|
||
|
|
int S::debug_impl (int) { /* <span class="roman">…</span> */ }
|
||
|
|
int S::optimized_impl (int) { /* <span class="roman">…</span> */ }
|
||
|
|
|
||
|
|
S::Func* S::resolver ()
|
||
|
|
{
|
||
|
|
int (S::*pimpl) (int)
|
||
|
|
= getenv ("DEBUG") ? &S::debug_impl : &S::optimized_impl;
|
||
|
|
|
||
|
|
// Cast triggers -Wno-pmf-conversions.
|
||
|
|
return reinterpret_cast<Func*>(pimpl);
|
||
|
|
}
|
||
|
|
|
||
|
|
int S::interface (int) __attribute__ ((ifunc ("_ZN1S8resolverEv")));
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>Indirect functions cannot be weak. Binutils version 2.20.1 or higher
|
||
|
|
and GNU C Library version 2.11.1 are required to use this feature.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>interrupt</code></dt>
|
||
|
|
<dt><code>interrupt_handler</code></dt>
|
||
|
|
<dd><p>Many GCC back ends support attributes to indicate that a function is
|
||
|
|
an interrupt handler, which tells the compiler to generate function
|
||
|
|
entry and exit sequences that differ from those from regular
|
||
|
|
functions. The exact syntax and behavior are target-specific;
|
||
|
|
refer to the following subsections for details.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>leaf</code></dt>
|
||
|
|
<dd><a name="index-leaf-function-attribute"></a>
|
||
|
|
<p>Calls to external functions with this attribute must return to the
|
||
|
|
current compilation unit only by return or by exception handling. In
|
||
|
|
particular, a leaf function is not allowed to invoke callback functions
|
||
|
|
passed to it from the current compilation unit, directly call functions
|
||
|
|
exported by the unit, or <code>longjmp</code> into the unit. Leaf functions
|
||
|
|
might still call functions from other compilation units and thus they
|
||
|
|
are not necessarily leaf in the sense that they contain no function
|
||
|
|
calls at all.
|
||
|
|
</p>
|
||
|
|
<p>The attribute is intended for library functions to improve dataflow
|
||
|
|
analysis. The compiler takes the hint that any data not escaping the
|
||
|
|
current compilation unit cannot be used or modified by the leaf
|
||
|
|
function. For example, the <code>sin</code> function is a leaf function, but
|
||
|
|
<code>qsort</code> is not.
|
||
|
|
</p>
|
||
|
|
<p>Note that leaf functions might indirectly run a signal handler defined
|
||
|
|
in the current compilation unit that uses static variables. Similarly,
|
||
|
|
when lazy symbol resolution is in effect, leaf functions might invoke
|
||
|
|
indirect functions whose resolver function or implementation function is
|
||
|
|
defined in the current compilation unit and uses static variables. There
|
||
|
|
is no standard-compliant way to write such a signal handler, resolver
|
||
|
|
function, or implementation function, and the best that you can do is to
|
||
|
|
remove the <code>leaf</code> attribute or mark all such static variables
|
||
|
|
<code>volatile</code>. Lastly, for ELF-based systems that support symbol
|
||
|
|
interposition, care should be taken that functions defined in the
|
||
|
|
current compilation unit do not unexpectedly interpose other symbols
|
||
|
|
based on the defined standards mode and defined feature test macros;
|
||
|
|
otherwise an inadvertent callback would be added.
|
||
|
|
</p>
|
||
|
|
<p>The attribute has no effect on functions defined within the current
|
||
|
|
compilation unit. This is to allow easy merging of multiple compilation
|
||
|
|
units into one, for example, by using the link-time optimization. For
|
||
|
|
this reason the attribute is not allowed on types to annotate indirect
|
||
|
|
calls.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>malloc</code></dt>
|
||
|
|
<dd><a name="index-malloc-function-attribute"></a>
|
||
|
|
<a name="index-functions-that-behave-like-malloc"></a>
|
||
|
|
<p>This tells the compiler that a function is <code>malloc</code>-like, i.e.,
|
||
|
|
that the pointer <var>P</var> returned by the function cannot alias any
|
||
|
|
other pointer valid when the function returns, and moreover no
|
||
|
|
pointers to valid objects occur in any storage addressed by <var>P</var>.
|
||
|
|
</p>
|
||
|
|
<p>Using this attribute can improve optimization. Functions like
|
||
|
|
<code>malloc</code> and <code>calloc</code> have this property because they return
|
||
|
|
a pointer to uninitialized or zeroed-out storage. However, functions
|
||
|
|
like <code>realloc</code> do not have this property, as they can return a
|
||
|
|
pointer to storage containing pointers.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>no_icf</code></dt>
|
||
|
|
<dd><a name="index-no_005ficf-function-attribute"></a>
|
||
|
|
<p>This function attribute prevents a functions from being merged with another
|
||
|
|
semantically equivalent function.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>no_instrument_function</code></dt>
|
||
|
|
<dd><a name="index-no_005finstrument_005ffunction-function-attribute"></a>
|
||
|
|
<a name="index-finstrument_002dfunctions-1"></a>
|
||
|
|
<p>If <samp>-finstrument-functions</samp> is given, profiling function calls are
|
||
|
|
generated at entry and exit of most user-compiled functions.
|
||
|
|
Functions with this attribute are not so instrumented.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>no_profile_instrument_function</code></dt>
|
||
|
|
<dd><a name="index-no_005fprofile_005finstrument_005ffunction-function-attribute"></a>
|
||
|
|
<p>The <code>no_profile_instrument_function</code> attribute on functions is used
|
||
|
|
to inform the compiler that it should not process any profile feedback based
|
||
|
|
optimization code instrumentation.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>no_reorder</code></dt>
|
||
|
|
<dd><a name="index-no_005freorder-function-attribute"></a>
|
||
|
|
<p>Do not reorder functions or variables marked <code>no_reorder</code>
|
||
|
|
against each other or top level assembler statements the executable.
|
||
|
|
The actual order in the program will depend on the linker command
|
||
|
|
line. Static variables marked like this are also not removed.
|
||
|
|
This has a similar effect
|
||
|
|
as the <samp>-fno-toplevel-reorder</samp> option, but only applies to the
|
||
|
|
marked symbols.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>no_sanitize ("<var>sanitize_option</var>")</code></dt>
|
||
|
|
<dd><a name="index-no_005fsanitize-function-attribute"></a>
|
||
|
|
<p>The <code>no_sanitize</code> attribute on functions is used
|
||
|
|
to inform the compiler that it should not do sanitization of all options
|
||
|
|
mentioned in <var>sanitize_option</var>. A list of values acceptable by
|
||
|
|
<samp>-fsanitize</samp> option can be provided.
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample">void __attribute__ ((no_sanitize ("alignment", "object-size")))
|
||
|
|
f () { /* <span class="roman">Do something.</span> */; }
|
||
|
|
void __attribute__ ((no_sanitize ("alignment,object-size")))
|
||
|
|
g () { /* <span class="roman">Do something.</span> */; }
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
</dd>
|
||
|
|
<dt><code>no_sanitize_address</code></dt>
|
||
|
|
<dt><code>no_address_safety_analysis</code></dt>
|
||
|
|
<dd><a name="index-no_005fsanitize_005faddress-function-attribute"></a>
|
||
|
|
<p>The <code>no_sanitize_address</code> attribute on functions is used
|
||
|
|
to inform the compiler that it should not instrument memory accesses
|
||
|
|
in the function when compiling with the <samp>-fsanitize=address</samp> option.
|
||
|
|
The <code>no_address_safety_analysis</code> is a deprecated alias of the
|
||
|
|
<code>no_sanitize_address</code> attribute, new code should use
|
||
|
|
<code>no_sanitize_address</code>.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>no_sanitize_thread</code></dt>
|
||
|
|
<dd><a name="index-no_005fsanitize_005fthread-function-attribute"></a>
|
||
|
|
<p>The <code>no_sanitize_thread</code> attribute on functions is used
|
||
|
|
to inform the compiler that it should not instrument memory accesses
|
||
|
|
in the function when compiling with the <samp>-fsanitize=thread</samp> option.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>no_sanitize_undefined</code></dt>
|
||
|
|
<dd><a name="index-no_005fsanitize_005fundefined-function-attribute"></a>
|
||
|
|
<p>The <code>no_sanitize_undefined</code> attribute on functions is used
|
||
|
|
to inform the compiler that it should not check for undefined behavior
|
||
|
|
in the function when compiling with the <samp>-fsanitize=undefined</samp> option.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>no_split_stack</code></dt>
|
||
|
|
<dd><a name="index-no_005fsplit_005fstack-function-attribute"></a>
|
||
|
|
<a name="index-fsplit_002dstack-1"></a>
|
||
|
|
<p>If <samp>-fsplit-stack</samp> is given, functions have a small
|
||
|
|
prologue which decides whether to split the stack. Functions with the
|
||
|
|
<code>no_split_stack</code> attribute do not have that prologue, and thus
|
||
|
|
may run with only a small amount of stack space available.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>no_stack_limit</code></dt>
|
||
|
|
<dd><a name="index-no_005fstack_005flimit-function-attribute"></a>
|
||
|
|
<p>This attribute locally overrides the <samp>-fstack-limit-register</samp>
|
||
|
|
and <samp>-fstack-limit-symbol</samp> command-line options; it has the effect
|
||
|
|
of disabling stack limit checking in the function it applies to.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>noclone</code></dt>
|
||
|
|
<dd><a name="index-noclone-function-attribute"></a>
|
||
|
|
<p>This function attribute prevents a function from being considered for
|
||
|
|
cloning—a mechanism that produces specialized copies of functions
|
||
|
|
and which is (currently) performed by interprocedural constant
|
||
|
|
propagation.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>noinline</code></dt>
|
||
|
|
<dd><a name="index-noinline-function-attribute"></a>
|
||
|
|
<p>This function attribute prevents a function from being considered for
|
||
|
|
inlining.
|
||
|
|
If the function does not have side effects, there are optimizations
|
||
|
|
other than inlining that cause function calls to be optimized away,
|
||
|
|
although the function call is live. To keep such calls from being
|
||
|
|
optimized away, put
|
||
|
|
</p><div class="smallexample">
|
||
|
|
<pre class="smallexample">asm ("");
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>(see <a href="Extended-Asm.html#Extended-Asm">Extended Asm</a>) in the called function, to serve as a special
|
||
|
|
side effect.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>noipa</code></dt>
|
||
|
|
<dd><a name="index-noipa-function-attribute"></a>
|
||
|
|
<p>Disable interprocedural optimizations between the function with this
|
||
|
|
attribute and its callers, as if the body of the function is not available
|
||
|
|
when optimizing callers and the callers are unavailable when optimizing
|
||
|
|
the body. This attribute implies <code>noinline</code>, <code>noclone</code> and
|
||
|
|
<code>no_icf</code> attributes. However, this attribute is not equivalent
|
||
|
|
to a combination of other attributes, because its purpose is to suppress
|
||
|
|
existing and future optimizations employing interprocedural analysis,
|
||
|
|
including those that do not have an attribute suitable for disabling
|
||
|
|
them individually. This attribute is supported mainly for the purpose
|
||
|
|
of testing the compiler.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>nonnull (<var>arg-index</var>, …)</code></dt>
|
||
|
|
<dd><a name="index-nonnull-function-attribute"></a>
|
||
|
|
<a name="index-functions-with-non_002dnull-pointer-arguments"></a>
|
||
|
|
<p>The <code>nonnull</code> attribute specifies that some function parameters should
|
||
|
|
be non-null pointers. For instance, the declaration:
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample">extern void *
|
||
|
|
my_memcpy (void *dest, const void *src, size_t len)
|
||
|
|
__attribute__((nonnull (1, 2)));
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<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 <samp>-Wnonnull</samp> option is enabled, a warning
|
||
|
|
is issued. The compiler may also choose to make optimizations based
|
||
|
|
on the knowledge that certain function arguments will never be null.
|
||
|
|
</p>
|
||
|
|
<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:
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample">extern void *
|
||
|
|
my_memcpy (void *dest, const void *src, size_t len)
|
||
|
|
__attribute__((nonnull));
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
</dd>
|
||
|
|
<dt><code>noplt</code></dt>
|
||
|
|
<dd><a name="index-noplt-function-attribute"></a>
|
||
|
|
<p>The <code>noplt</code> attribute is the counterpart to option <samp>-fno-plt</samp>.
|
||
|
|
Calls to functions marked with this attribute in position-independent code
|
||
|
|
do not use the PLT.
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample">/* Externally defined function foo. */
|
||
|
|
int foo () __attribute__ ((noplt));
|
||
|
|
|
||
|
|
int
|
||
|
|
main (/* <span class="roman">…</span> */)
|
||
|
|
{
|
||
|
|
/* <span class="roman">…</span> */
|
||
|
|
foo ();
|
||
|
|
/* <span class="roman">…</span> */
|
||
|
|
}
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>The <code>noplt</code> attribute on function <code>foo</code>
|
||
|
|
tells the compiler to assume that
|
||
|
|
the function <code>foo</code> is externally defined and that the call to
|
||
|
|
<code>foo</code> must avoid the PLT
|
||
|
|
in position-independent code.
|
||
|
|
</p>
|
||
|
|
<p>In position-dependent code, a few targets also convert calls to
|
||
|
|
functions that are marked to not use the PLT to use the GOT instead.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>noreturn</code></dt>
|
||
|
|
<dd><a name="index-noreturn-function-attribute"></a>
|
||
|
|
<a name="index-functions-that-never-return"></a>
|
||
|
|
<p>A few standard library functions, such as <code>abort</code> and <code>exit</code>,
|
||
|
|
cannot return. GCC knows this automatically. Some programs define
|
||
|
|
their own functions that never return. You can declare them
|
||
|
|
<code>noreturn</code> to tell the compiler this fact. For example,
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample">void fatal () __attribute__ ((noreturn));
|
||
|
|
|
||
|
|
void
|
||
|
|
fatal (/* <span class="roman">…</span> */)
|
||
|
|
{
|
||
|
|
/* <span class="roman">…</span> */ /* <span class="roman">Print error message.</span> */ /* <span class="roman">…</span> */
|
||
|
|
exit (1);
|
||
|
|
}
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>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.
|
||
|
|
</p>
|
||
|
|
<p>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>.
|
||
|
|
</p>
|
||
|
|
<p>Do not assume that registers saved by the calling function are
|
||
|
|
restored before calling the <code>noreturn</code> function.
|
||
|
|
</p>
|
||
|
|
<p>It does not make sense for a <code>noreturn</code> function to have a return
|
||
|
|
type other than <code>void</code>.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>nothrow</code></dt>
|
||
|
|
<dd><a name="index-nothrow-function-attribute"></a>
|
||
|
|
<p>The <code>nothrow</code> attribute is used to inform the compiler that a
|
||
|
|
function cannot throw an exception. For example, most functions in
|
||
|
|
the standard C library can be guaranteed not to throw an exception
|
||
|
|
with the notable exceptions of <code>qsort</code> and <code>bsearch</code> that
|
||
|
|
take function pointer arguments.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>optimize</code></dt>
|
||
|
|
<dd><a name="index-optimize-function-attribute"></a>
|
||
|
|
<p>The <code>optimize</code> attribute is used to specify that a function is to
|
||
|
|
be compiled with different optimization options than specified on the
|
||
|
|
command line. Arguments can either be numbers or strings. Numbers
|
||
|
|
are assumed to be an optimization level. Strings that begin with
|
||
|
|
<code>O</code> are assumed to be an optimization option, while other options
|
||
|
|
are assumed to be used with a <code>-f</code> prefix. You can also use the
|
||
|
|
‘<samp>#pragma GCC optimize</samp>’ pragma to set the optimization options
|
||
|
|
that affect more than one function.
|
||
|
|
See <a href="Function-Specific-Option-Pragmas.html#Function-Specific-Option-Pragmas">Function Specific Option Pragmas</a>, for details about the
|
||
|
|
‘<samp>#pragma GCC optimize</samp>’ pragma.
|
||
|
|
</p>
|
||
|
|
<p>This attribute should be used for debugging purposes only. It is not
|
||
|
|
suitable in production code.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>patchable_function_entry</code></dt>
|
||
|
|
<dd><a name="index-patchable_005ffunction_005fentry-function-attribute"></a>
|
||
|
|
<a name="index-extra-NOP-instructions-at-the-function-entry-point"></a>
|
||
|
|
<p>In case the target’s text segment can be made writable at run time by
|
||
|
|
any means, padding the function entry with a number of NOPs can be
|
||
|
|
used to provide a universal tool for instrumentation.
|
||
|
|
</p>
|
||
|
|
<p>The <code>patchable_function_entry</code> function attribute can be used to
|
||
|
|
change the number of NOPs to any desired value. The two-value syntax
|
||
|
|
is the same as for the command-line switch
|
||
|
|
<samp>-fpatchable-function-entry=N,M</samp>, generating <var>N</var> NOPs, with
|
||
|
|
the function entry point before the <var>M</var>th NOP instruction.
|
||
|
|
<var>M</var> defaults to 0 if omitted e.g. function entry point is before
|
||
|
|
the first NOP.
|
||
|
|
</p>
|
||
|
|
<p>If patchable function entries are enabled globally using the command-line
|
||
|
|
option <samp>-fpatchable-function-entry=N,M</samp>, then you must disable
|
||
|
|
instrumentation on all functions that are part of the instrumentation
|
||
|
|
framework with the attribute <code>patchable_function_entry (0)</code>
|
||
|
|
to prevent recursion.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>pure</code></dt>
|
||
|
|
<dd><a name="index-pure-function-attribute"></a>
|
||
|
|
<a name="index-functions-that-have-no-side-effects-1"></a>
|
||
|
|
<p>Many functions have no effects except the return value and their
|
||
|
|
return value depends only on the parameters and/or global variables.
|
||
|
|
Calls to such functions can be subject
|
||
|
|
to common subexpression elimination and loop optimization just as an
|
||
|
|
arithmetic operator would be. These functions should be declared
|
||
|
|
with the attribute <code>pure</code>. For example,
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample">int square (int) __attribute__ ((pure));
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>says that the hypothetical function <code>square</code> is safe to call
|
||
|
|
fewer times than the program says.
|
||
|
|
</p>
|
||
|
|
<p>Some 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).
|
||
|
|
</p>
|
||
|
|
<p>The <code>pure</code> attribute imposes similar but looser restrictions on
|
||
|
|
a function’s defintion than the <code>const</code> attribute: it allows the
|
||
|
|
function to read global variables. Decorating the same function with
|
||
|
|
both the <code>pure</code> and the <code>const</code> attribute is diagnosed.
|
||
|
|
Because a <code>pure</code> function cannot have any side effects it does not
|
||
|
|
make sense for such a function to return <code>void</code>. Declaring such
|
||
|
|
a function is diagnosed.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>returns_nonnull</code></dt>
|
||
|
|
<dd><a name="index-returns_005fnonnull-function-attribute"></a>
|
||
|
|
<p>The <code>returns_nonnull</code> attribute specifies that the function
|
||
|
|
return value should be a non-null pointer. For instance, the declaration:
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample">extern void *
|
||
|
|
mymalloc (size_t len) __attribute__((returns_nonnull));
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>lets the compiler optimize callers based on the knowledge
|
||
|
|
that the return value will never be null.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>returns_twice</code></dt>
|
||
|
|
<dd><a name="index-returns_005ftwice-function-attribute"></a>
|
||
|
|
<a name="index-functions-that-return-more-than-once"></a>
|
||
|
|
<p>The <code>returns_twice</code> attribute tells the compiler that a function may
|
||
|
|
return more than one time. The compiler ensures that all registers
|
||
|
|
are dead before calling such a function and emits a warning about
|
||
|
|
the variables that may be clobbered after the second return from the
|
||
|
|
function. Examples of such functions are <code>setjmp</code> and <code>vfork</code>.
|
||
|
|
The <code>longjmp</code>-like counterpart of such function, if any, might need
|
||
|
|
to be marked with the <code>noreturn</code> attribute.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>section ("<var>section-name</var>")</code></dt>
|
||
|
|
<dd><a name="index-section-function-attribute"></a>
|
||
|
|
<a name="index-functions-in-arbitrary-sections"></a>
|
||
|
|
<p>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:
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample">extern void foobar (void) __attribute__ ((section ("bar")));
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>puts the function <code>foobar</code> in the <code>bar</code> section.
|
||
|
|
</p>
|
||
|
|
<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.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>sentinel</code></dt>
|
||
|
|
<dd><a name="index-sentinel-function-attribute"></a>
|
||
|
|
<p>This function attribute ensures that a parameter in a function call is
|
||
|
|
an explicit <code>NULL</code>. The attribute is only valid on variadic
|
||
|
|
functions. By default, the sentinel is located at position zero, the
|
||
|
|
last parameter of the function call. If an optional integer position
|
||
|
|
argument P is supplied to the attribute, the sentinel must be located at
|
||
|
|
position P counting backwards from the end of the argument list.
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample">__attribute__ ((sentinel))
|
||
|
|
is equivalent to
|
||
|
|
__attribute__ ((sentinel(0)))
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>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.
|
||
|
|
</p>
|
||
|
|
<p>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.
|
||
|
|
</p>
|
||
|
|
<p>The warnings for missing or incorrect sentinels are enabled with
|
||
|
|
<samp>-Wformat</samp>.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>simd</code></dt>
|
||
|
|
<dt><code>simd("<var>mask</var>")</code></dt>
|
||
|
|
<dd><a name="index-simd-function-attribute"></a>
|
||
|
|
<p>This attribute enables creation of one or more function versions that
|
||
|
|
can process multiple arguments using SIMD instructions from a
|
||
|
|
single invocation. Specifying this attribute allows compiler to
|
||
|
|
assume that such versions are available at link time (provided
|
||
|
|
in the same or another translation unit). Generated versions are
|
||
|
|
target-dependent and described in the corresponding Vector ABI document. For
|
||
|
|
x86_64 target this document can be found
|
||
|
|
<a href="https://sourceware.org/glibc/wiki/libmvec?action=AttachFile&do=view&target=VectorABI.txt">here</a><!-- /@w -->.
|
||
|
|
</p>
|
||
|
|
<p>The optional argument <var>mask</var> may have the value
|
||
|
|
<code>notinbranch</code> or <code>inbranch</code>,
|
||
|
|
and instructs the compiler to generate non-masked or masked
|
||
|
|
clones correspondingly. By default, all clones are generated.
|
||
|
|
</p>
|
||
|
|
<p>If the attribute is specified and <code>#pragma omp declare simd</code> is
|
||
|
|
present on a declaration and the <samp>-fopenmp</samp> or <samp>-fopenmp-simd</samp>
|
||
|
|
switch is specified, then the attribute is ignored.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>stack_protect</code></dt>
|
||
|
|
<dd><a name="index-stack_005fprotect-function-attribute"></a>
|
||
|
|
<p>This attribute adds stack protection code to the function if
|
||
|
|
flags <samp>-fstack-protector</samp>, <samp>-fstack-protector-strong</samp>
|
||
|
|
or <samp>-fstack-protector-explicit</samp> are set.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>target (<var>options</var>)</code></dt>
|
||
|
|
<dd><a name="index-target-function-attribute"></a>
|
||
|
|
<p>Multiple target back ends implement the <code>target</code> attribute
|
||
|
|
to specify that a function is to
|
||
|
|
be compiled with different target options than specified on the
|
||
|
|
command line. This can be used for instance to have functions
|
||
|
|
compiled with a different ISA (instruction set architecture) than the
|
||
|
|
default. You can also use the ‘<samp>#pragma GCC target</samp>’ pragma to set
|
||
|
|
more than one function to be compiled with specific target options.
|
||
|
|
See <a href="Function-Specific-Option-Pragmas.html#Function-Specific-Option-Pragmas">Function Specific Option Pragmas</a>, for details about the
|
||
|
|
‘<samp>#pragma GCC target</samp>’ pragma.
|
||
|
|
</p>
|
||
|
|
<p>For instance, on an x86, you could declare one function with the
|
||
|
|
<code>target("sse4.1,arch=core2")</code> attribute and another with
|
||
|
|
<code>target("sse4a,arch=amdfam10")</code>. This is equivalent to
|
||
|
|
compiling the first function with <samp>-msse4.1</samp> and
|
||
|
|
<samp>-march=core2</samp> options, and the second function with
|
||
|
|
<samp>-msse4a</samp> and <samp>-march=amdfam10</samp> options. It is up to you
|
||
|
|
to make sure that a function is only invoked on a machine that
|
||
|
|
supports the particular ISA it is compiled for (for example by using
|
||
|
|
<code>cpuid</code> on x86 to determine what feature bits and architecture
|
||
|
|
family are used).
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample">int core2_func (void) __attribute__ ((__target__ ("arch=core2")));
|
||
|
|
int sse3_func (void) __attribute__ ((__target__ ("sse3")));
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>You can either use multiple
|
||
|
|
strings separated by commas to specify multiple options,
|
||
|
|
or separate the options with a comma (‘<samp>,</samp>’) within a single string.
|
||
|
|
</p>
|
||
|
|
<p>The options supported are specific to each target; refer to <a href="x86-Function-Attributes.html#x86-Function-Attributes">x86 Function Attributes</a>, <a href="PowerPC-Function-Attributes.html#PowerPC-Function-Attributes">PowerPC Function Attributes</a>,
|
||
|
|
<a href="ARM-Function-Attributes.html#ARM-Function-Attributes">ARM Function Attributes</a>, <a href="AArch64-Function-Attributes.html#AArch64-Function-Attributes">AArch64 Function Attributes</a>,
|
||
|
|
<a href="Nios-II-Function-Attributes.html#Nios-II-Function-Attributes">Nios II Function Attributes</a>, and <a href="S_002f390-Function-Attributes.html#S_002f390-Function-Attributes">S/390 Function Attributes</a>
|
||
|
|
for details.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>target_clones (<var>options</var>)</code></dt>
|
||
|
|
<dd><a name="index-target_005fclones-function-attribute"></a>
|
||
|
|
<p>The <code>target_clones</code> attribute is used to specify that a function
|
||
|
|
be cloned into multiple versions compiled with different target options
|
||
|
|
than specified on the command line. The supported options and restrictions
|
||
|
|
are the same as for <code>target</code> attribute.
|
||
|
|
</p>
|
||
|
|
<p>For instance, on an x86, you could compile a function with
|
||
|
|
<code>target_clones("sse4.1,avx")</code>. GCC creates two function clones,
|
||
|
|
one compiled with <samp>-msse4.1</samp> and another with <samp>-mavx</samp>.
|
||
|
|
</p>
|
||
|
|
<p>On a PowerPC, you can compile a function with
|
||
|
|
<code>target_clones("cpu=power9,default")</code>. GCC will create two
|
||
|
|
function clones, one compiled with <samp>-mcpu=power9</samp> and another
|
||
|
|
with the default options. GCC must be configured to use GLIBC 2.23 or
|
||
|
|
newer in order to use the <code>target_clones</code> attribute.
|
||
|
|
</p>
|
||
|
|
<p>It also creates a resolver function (see
|
||
|
|
the <code>ifunc</code> attribute above) that dynamically selects a clone
|
||
|
|
suitable for current architecture. The resolver is created only if there
|
||
|
|
is a usage of a function with <code>target_clones</code> attribute.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>unused</code></dt>
|
||
|
|
<dd><a name="index-unused-function-attribute"></a>
|
||
|
|
<p>This attribute, attached to a function, means that the function is meant
|
||
|
|
to be possibly unused. GCC does not produce a warning for this
|
||
|
|
function.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>used</code></dt>
|
||
|
|
<dd><a name="index-used-function-attribute"></a>
|
||
|
|
<p>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.
|
||
|
|
</p>
|
||
|
|
<p>When applied to a member function of a C++ class template, the
|
||
|
|
attribute also means that the function is instantiated if the
|
||
|
|
class itself is instantiated.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>visibility ("<var>visibility_type</var>")</code></dt>
|
||
|
|
<dd><a name="index-visibility-function-attribute"></a>
|
||
|
|
<p>This attribute affects the linkage of the declaration to which it is attached.
|
||
|
|
It can be applied to variables (see <a href="Common-Variable-Attributes.html#Common-Variable-Attributes">Common Variable Attributes</a>) and types
|
||
|
|
(see <a href="Common-Type-Attributes.html#Common-Type-Attributes">Common Type Attributes</a>) as well as functions.
|
||
|
|
</p>
|
||
|
|
<p>There are four supported <var>visibility_type</var> values: default,
|
||
|
|
hidden, protected or internal visibility.
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample">void __attribute__ ((visibility ("protected")))
|
||
|
|
f () { /* <span class="roman">Do something.</span> */; }
|
||
|
|
int i __attribute__ ((visibility ("hidden")));
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>The possible values of <var>visibility_type</var> correspond to the
|
||
|
|
visibility settings in the ELF gABI.
|
||
|
|
</p>
|
||
|
|
<dl compact="compact">
|
||
|
|
<dt><code>default</code></dt>
|
||
|
|
<dd><p>Default visibility is the normal case for the object file format.
|
||
|
|
This value is available for the visibility attribute to override other
|
||
|
|
options that may change the assumed visibility of entities.
|
||
|
|
</p>
|
||
|
|
<p>On ELF, default visibility means that the declaration is visible to other
|
||
|
|
modules and, in shared libraries, means that the declared entity may be
|
||
|
|
overridden.
|
||
|
|
</p>
|
||
|
|
<p>On Darwin, default visibility means that the declaration is visible to
|
||
|
|
other modules.
|
||
|
|
</p>
|
||
|
|
<p>Default visibility corresponds to “external linkage” in the language.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>hidden</code></dt>
|
||
|
|
<dd><p>Hidden visibility indicates that the entity declared has a new
|
||
|
|
form of linkage, which we call “hidden linkage”. Two
|
||
|
|
declarations of an object with hidden linkage refer to the same object
|
||
|
|
if they are in the same shared object.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>internal</code></dt>
|
||
|
|
<dd><p>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 a function is
|
||
|
|
<em>never</em> called from another module. Compare this with hidden
|
||
|
|
functions which, while they cannot be referenced directly by other
|
||
|
|
modules, can be referenced indirectly via function pointers. By
|
||
|
|
indicating that a function 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.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>protected</code></dt>
|
||
|
|
<dd><p>Protected visibility is like default visibility except that it
|
||
|
|
indicates that references within the defining module bind to the
|
||
|
|
definition in that module. That is, the declared entity cannot be
|
||
|
|
overridden by another module.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<p>All visibilities are supported on many, but not all, ELF targets
|
||
|
|
(supported when the assembler supports the ‘<samp>.visibility</samp>’
|
||
|
|
pseudo-op). Default visibility is supported everywhere. Hidden
|
||
|
|
visibility is supported on Darwin targets.
|
||
|
|
</p>
|
||
|
|
<p>The visibility attribute should be applied only to declarations that
|
||
|
|
would otherwise have external linkage. The attribute should be applied
|
||
|
|
consistently, so that the same entity should not be declared with
|
||
|
|
different settings of the attribute.
|
||
|
|
</p>
|
||
|
|
<p>In C++, the visibility attribute applies to types as well as functions
|
||
|
|
and objects, because in C++ types have linkage. A class must not have
|
||
|
|
greater visibility than its non-static data member types and bases,
|
||
|
|
and class members default to the visibility of their class. Also, a
|
||
|
|
declaration without explicit visibility is limited to the visibility
|
||
|
|
of its type.
|
||
|
|
</p>
|
||
|
|
<p>In C++, you can mark member functions and static member variables of a
|
||
|
|
class with the visibility attribute. This is useful if you know a
|
||
|
|
particular method or static member variable should only be used from
|
||
|
|
one shared object; then you can mark it hidden while the rest of the
|
||
|
|
class has default visibility. Care must be taken to avoid breaking
|
||
|
|
the One Definition Rule; for example, it is usually not useful to mark
|
||
|
|
an inline method as hidden without marking the whole class as hidden.
|
||
|
|
</p>
|
||
|
|
<p>A C++ namespace declaration can also have the visibility attribute.
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample">namespace nspace1 __attribute__ ((visibility ("protected")))
|
||
|
|
{ /* <span class="roman">Do something.</span> */; }
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>This attribute applies only to the particular namespace body, not to
|
||
|
|
other definitions of the same namespace; it is equivalent to using
|
||
|
|
‘<samp>#pragma GCC visibility</samp>’ before and after the namespace
|
||
|
|
definition (see <a href="Visibility-Pragmas.html#Visibility-Pragmas">Visibility Pragmas</a>).
|
||
|
|
</p>
|
||
|
|
<p>In C++, if a template argument has limited visibility, this
|
||
|
|
restriction is implicitly propagated to the template instantiation.
|
||
|
|
Otherwise, template instantiations and specializations default to the
|
||
|
|
visibility of their template.
|
||
|
|
</p>
|
||
|
|
<p>If both the template and enclosing class have explicit visibility, the
|
||
|
|
visibility from the template is used.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>warn_unused_result</code></dt>
|
||
|
|
<dd><a name="index-warn_005funused_005fresult-function-attribute"></a>
|
||
|
|
<p>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>.
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample">int fn () __attribute__ ((warn_unused_result));
|
||
|
|
int foo ()
|
||
|
|
{
|
||
|
|
if (fn () < 0) return -1;
|
||
|
|
fn ();
|
||
|
|
return 0;
|
||
|
|
}
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>results in warning on line 5.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>weak</code></dt>
|
||
|
|
<dd><a name="index-weak-function-attribute"></a>
|
||
|
|
<p>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 that 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.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>weakref</code></dt>
|
||
|
|
<dt><code>weakref ("<var>target</var>")</code></dt>
|
||
|
|
<dd><a name="index-weakref-function-attribute"></a>
|
||
|
|
<p>The <code>weakref</code> attribute marks a declaration as a weak reference.
|
||
|
|
Without arguments, it should be accompanied by an <code>alias</code> attribute
|
||
|
|
naming the target symbol. Optionally, the <var>target</var> may be given as
|
||
|
|
an argument to <code>weakref</code> itself. In either case, <code>weakref</code>
|
||
|
|
implicitly marks the declaration as <code>weak</code>. Without a
|
||
|
|
<var>target</var>, given as an argument to <code>weakref</code> or to <code>alias</code>,
|
||
|
|
<code>weakref</code> is equivalent to <code>weak</code>.
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample">static int x() __attribute__ ((weakref ("y")));
|
||
|
|
/* is equivalent to... */
|
||
|
|
static int x() __attribute__ ((weak, weakref, alias ("y")));
|
||
|
|
/* and to... */
|
||
|
|
static int x() __attribute__ ((weakref));
|
||
|
|
static int x() __attribute__ ((alias ("y")));
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>A weak reference is an alias that does not by itself require a
|
||
|
|
definition to be given for the target symbol. If the target symbol is
|
||
|
|
only referenced through weak references, then it becomes a <code>weak</code>
|
||
|
|
undefined symbol. If it is directly referenced, however, then such
|
||
|
|
strong references prevail, and a definition is required for the
|
||
|
|
symbol, not necessarily in the same translation unit.
|
||
|
|
</p>
|
||
|
|
<p>The effect is equivalent to moving all references to the alias to a
|
||
|
|
separate translation unit, renaming the alias to the aliased symbol,
|
||
|
|
declaring it as weak, compiling the two separate translation units and
|
||
|
|
performing a reloadable link on them.
|
||
|
|
</p>
|
||
|
|
<p>At present, a declaration to which <code>weakref</code> is attached can
|
||
|
|
only be <code>static</code>.
|
||
|
|
</p>
|
||
|
|
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
|
||
|
|
<hr>
|
||
|
|
<div class="header">
|
||
|
|
<p>
|
||
|
|
Next: <a href="AArch64-Function-Attributes.html#AArch64-Function-Attributes" accesskey="n" rel="next">AArch64 Function Attributes</a>, Up: <a href="Function-Attributes.html#Function-Attributes" accesskey="u" rel="up">Function Attributes</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Option-Index.html#Option-Index" title="Index" rel="index">Index</a>]</p>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
</body>
|
||
|
|
</html>
|