379 lines
17 KiB
HTML
379 lines
17 KiB
HTML
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
||
|
|
<html>
|
||
|
|
<!-- Copyright (C) 1988-2016 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 5.2, http://www.gnu.org/software/texinfo/ -->
|
||
|
|
<head>
|
||
|
|
<title>Using the GNU Compiler Collection (GCC): Common Variable Attributes</title>
|
||
|
|
|
||
|
|
<meta name="description" content="Using the GNU Compiler Collection (GCC): Common Variable Attributes">
|
||
|
|
<meta name="keywords" content="Using the GNU Compiler Collection (GCC): Common Variable Attributes">
|
||
|
|
<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="Variable-Attributes.html#Variable-Attributes" rel="up" title="Variable Attributes">
|
||
|
|
<link href="AVR-Variable-Attributes.html#AVR-Variable-Attributes" rel="next" title="AVR Variable Attributes">
|
||
|
|
<link href="Variable-Attributes.html#Variable-Attributes" rel="prev" title="Variable Attributes">
|
||
|
|
<style type="text/css">
|
||
|
|
<!--
|
||
|
|
a.summary-letter {text-decoration: none}
|
||
|
|
blockquote.smallquotation {font-size: smaller}
|
||
|
|
div.display {margin-left: 3.2em}
|
||
|
|
div.example {margin-left: 3.2em}
|
||
|
|
div.indentedblock {margin-left: 3.2em}
|
||
|
|
div.lisp {margin-left: 3.2em}
|
||
|
|
div.smalldisplay {margin-left: 3.2em}
|
||
|
|
div.smallexample {margin-left: 3.2em}
|
||
|
|
div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
|
||
|
|
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.nocodebreak {white-space:nowrap}
|
||
|
|
span.nolinebreak {white-space:nowrap}
|
||
|
|
span.roman {font-family:serif; font-weight:normal}
|
||
|
|
span.sansserif {font-family:sans-serif; font-weight:normal}
|
||
|
|
ul.no-bullet {list-style: none}
|
||
|
|
-->
|
||
|
|
</style>
|
||
|
|
|
||
|
|
|
||
|
|
</head>
|
||
|
|
|
||
|
|
<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
|
||
|
|
<a name="Common-Variable-Attributes"></a>
|
||
|
|
<div class="header">
|
||
|
|
<p>
|
||
|
|
Next: <a href="AVR-Variable-Attributes.html#AVR-Variable-Attributes" accesskey="n" rel="next">AVR Variable Attributes</a>, Up: <a href="Variable-Attributes.html#Variable-Attributes" accesskey="u" rel="up">Variable 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-Variable-Attributes-1"></a>
|
||
|
|
<h4 class="subsection">6.32.1 Common Variable Attributes</h4>
|
||
|
|
|
||
|
|
<p>The following attributes are supported on most targets.
|
||
|
|
</p>
|
||
|
|
<dl compact="compact">
|
||
|
|
<dd><a name="index-aligned-variable-attribute"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>aligned (<var>alignment</var>)</code></dt>
|
||
|
|
<dd><p>This attribute specifies a minimum alignment for the variable or
|
||
|
|
structure field, measured in bytes. For example, the declaration:
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample">int x __attribute__ ((aligned (16))) = 0;
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>causes the compiler to allocate the global variable <code>x</code> on a
|
||
|
|
16-byte boundary. On a 68040, this could be used in conjunction with
|
||
|
|
an <code>asm</code> expression to access the <code>move16</code> instruction which
|
||
|
|
requires 16-byte aligned operands.
|
||
|
|
</p>
|
||
|
|
<p>You can also specify the alignment of structure fields. For example, to
|
||
|
|
create a double-word aligned <code>int</code> pair, you could write:
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample">struct foo { int x[2] __attribute__ ((aligned (8))); };
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>This is an alternative to creating a union with a <code>double</code> member,
|
||
|
|
which forces the union to be double-word aligned.
|
||
|
|
</p>
|
||
|
|
<p>As in the preceding examples, you can explicitly specify the alignment
|
||
|
|
(in bytes) that you wish the compiler to use for a given variable or
|
||
|
|
structure field. Alternatively, you can leave out the alignment factor
|
||
|
|
and just ask the compiler to align a variable or field to the
|
||
|
|
default alignment for the target architecture you are compiling for.
|
||
|
|
The default alignment is sufficient for all scalar types, but may not be
|
||
|
|
enough for all vector types on a target that supports vector operations.
|
||
|
|
The default alignment is fixed for a particular target ABI.
|
||
|
|
</p>
|
||
|
|
<p>GCC also provides a target specific macro <code>__BIGGEST_ALIGNMENT__</code>,
|
||
|
|
which is the largest alignment ever used for any data type on the
|
||
|
|
target machine you are compiling for. For example, you could write:
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample">short array[3] __attribute__ ((aligned (__BIGGEST_ALIGNMENT__)));
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>The compiler automatically sets the alignment for the declared
|
||
|
|
variable or field to <code>__BIGGEST_ALIGNMENT__</code>. Doing this can
|
||
|
|
often make copy operations more efficient, because the compiler can
|
||
|
|
use whatever instructions copy the biggest chunks of memory when
|
||
|
|
performing copies to or from the variables or fields that you have
|
||
|
|
aligned this way. Note that the value of <code>__BIGGEST_ALIGNMENT__</code>
|
||
|
|
may change depending on command-line options.
|
||
|
|
</p>
|
||
|
|
<p>When used on a struct, or struct member, the <code>aligned</code> attribute can
|
||
|
|
only increase the alignment; in order to decrease it, the <code>packed</code>
|
||
|
|
attribute must be specified as well. When used as part of a typedef, the
|
||
|
|
<code>aligned</code> attribute can both increase and decrease alignment, and
|
||
|
|
specifying the <code>packed</code> attribute generates a warning.
|
||
|
|
</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 variables to be aligned up to a certain maximum
|
||
|
|
alignment. (For some linkers, the maximum supported alignment may
|
||
|
|
be very very small.) If your linker is only able to align variables
|
||
|
|
up to a maximum of 8-byte alignment, then specifying <code>aligned(16)</code>
|
||
|
|
in an <code>__attribute__</code> still only provides you with 8-byte
|
||
|
|
alignment. See your linker documentation for further information.
|
||
|
|
</p>
|
||
|
|
<p>The <code>aligned</code> attribute can also be used for functions
|
||
|
|
(see <a href="Common-Function-Attributes.html#Common-Function-Attributes">Common Function Attributes</a>.)
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>cleanup (<var>cleanup_function</var>)</code></dt>
|
||
|
|
<dd><a name="index-cleanup-variable-attribute"></a>
|
||
|
|
<p>The <code>cleanup</code> attribute runs a function when the variable goes
|
||
|
|
out of scope. This attribute can only be applied to auto function
|
||
|
|
scope variables; it may not be applied to parameters or variables
|
||
|
|
with static storage duration. The function must take one parameter,
|
||
|
|
a pointer to a type compatible with the variable. The return value
|
||
|
|
of the function (if any) is ignored.
|
||
|
|
</p>
|
||
|
|
<p>If <samp>-fexceptions</samp> is enabled, then <var>cleanup_function</var>
|
||
|
|
is run during the stack unwinding that happens during the
|
||
|
|
processing of the exception. Note that the <code>cleanup</code> attribute
|
||
|
|
does not allow the exception to be caught, only to perform an action.
|
||
|
|
It is undefined what happens if <var>cleanup_function</var> does not
|
||
|
|
return normally.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>common</code></dt>
|
||
|
|
<dt><code>nocommon</code></dt>
|
||
|
|
<dd><a name="index-common-variable-attribute"></a>
|
||
|
|
<a name="index-nocommon-variable-attribute"></a>
|
||
|
|
<a name="index-fcommon"></a>
|
||
|
|
<a name="index-fno_002dcommon-1"></a>
|
||
|
|
<p>The <code>common</code> attribute requests GCC to place a variable in
|
||
|
|
“common” storage. The <code>nocommon</code> attribute requests the
|
||
|
|
opposite—to allocate space for it directly.
|
||
|
|
</p>
|
||
|
|
<p>These attributes override the default chosen by the
|
||
|
|
<samp>-fno-common</samp> and <samp>-fcommon</samp> flags respectively.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>deprecated</code></dt>
|
||
|
|
<dt><code>deprecated (<var>msg</var>)</code></dt>
|
||
|
|
<dd><a name="index-deprecated-variable-attribute"></a>
|
||
|
|
<p>The <code>deprecated</code> attribute results in a warning if the variable
|
||
|
|
is used anywhere in the source file. This is useful when identifying
|
||
|
|
variables 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 variable, to enable users to easily find further
|
||
|
|
information about why the variable is deprecated, or what they should
|
||
|
|
do instead. Note that the warning only occurs for uses:
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample">extern int old_var __attribute__ ((deprecated));
|
||
|
|
extern int old_var;
|
||
|
|
int new_fn () { return old_var; }
|
||
|
|
</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 functions and
|
||
|
|
types (see <a href="Common-Function-Attributes.html#Common-Function-Attributes">Common Function Attributes</a>,
|
||
|
|
see <a href="Common-Type-Attributes.html#Common-Type-Attributes">Common Type Attributes</a>).
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>mode (<var>mode</var>)</code></dt>
|
||
|
|
<dd><a name="index-mode-variable-attribute"></a>
|
||
|
|
<p>This attribute specifies the data type for the declaration—whichever
|
||
|
|
type corresponds to the mode <var>mode</var>. This in effect lets you
|
||
|
|
request an integer or floating-point type according to its width.
|
||
|
|
</p>
|
||
|
|
<p>You may also specify a mode of <code>byte</code> or <code>__byte__</code> to
|
||
|
|
indicate the mode corresponding to a one-byte integer, <code>word</code> or
|
||
|
|
<code>__word__</code> for the mode of a one-word integer, and <code>pointer</code>
|
||
|
|
or <code>__pointer__</code> for the mode used to represent pointers.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>packed</code></dt>
|
||
|
|
<dd><a name="index-packed-variable-attribute"></a>
|
||
|
|
<p>The <code>packed</code> attribute specifies that a variable or structure field
|
||
|
|
should have the smallest possible alignment—one byte for a variable,
|
||
|
|
and one bit for a field, unless you specify a larger value with the
|
||
|
|
<code>aligned</code> attribute.
|
||
|
|
</p>
|
||
|
|
<p>Here is a structure in which the field <code>x</code> is packed, so that it
|
||
|
|
immediately follows <code>a</code>:
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample">struct foo
|
||
|
|
{
|
||
|
|
char a;
|
||
|
|
int x[2] __attribute__ ((packed));
|
||
|
|
};
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p><em>Note:</em> The 4.1, 4.2 and 4.3 series of GCC ignore the
|
||
|
|
<code>packed</code> attribute on bit-fields of type <code>char</code>. This has
|
||
|
|
been fixed in GCC 4.4 but the change can lead to differences in the
|
||
|
|
structure layout. See the documentation of
|
||
|
|
<samp>-Wpacked-bitfield-compat</samp> for more information.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>section ("<var>section-name</var>")</code></dt>
|
||
|
|
<dd><a name="index-section-variable-attribute"></a>
|
||
|
|
<p>Normally, the compiler places the objects it generates in sections like
|
||
|
|
<code>data</code> and <code>bss</code>. Sometimes, however, you need additional sections,
|
||
|
|
or you need certain particular variables to appear in special sections,
|
||
|
|
for example to map to special hardware. The <code>section</code>
|
||
|
|
attribute specifies that a variable (or function) lives in a particular
|
||
|
|
section. For example, this small program uses several specific section names:
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample">struct duart a __attribute__ ((section ("DUART_A"))) = { 0 };
|
||
|
|
struct duart b __attribute__ ((section ("DUART_B"))) = { 0 };
|
||
|
|
char stack[10000] __attribute__ ((section ("STACK"))) = { 0 };
|
||
|
|
int init_data __attribute__ ((section ("INITDATA")));
|
||
|
|
|
||
|
|
main()
|
||
|
|
{
|
||
|
|
/* <span class="roman">Initialize stack pointer</span> */
|
||
|
|
init_sp (stack + sizeof (stack));
|
||
|
|
|
||
|
|
/* <span class="roman">Initialize initialized data</span> */
|
||
|
|
memcpy (&init_data, &data, &edata - &data);
|
||
|
|
|
||
|
|
/* <span class="roman">Turn on the serial ports</span> */
|
||
|
|
init_duart (&a);
|
||
|
|
init_duart (&b);
|
||
|
|
}
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>Use the <code>section</code> attribute with
|
||
|
|
<em>global</em> variables and not <em>local</em> variables,
|
||
|
|
as shown in the example.
|
||
|
|
</p>
|
||
|
|
<p>You may use the <code>section</code> attribute with initialized or
|
||
|
|
uninitialized global variables but the linker requires
|
||
|
|
each object be defined once, with the exception that uninitialized
|
||
|
|
variables tentatively go in the <code>common</code> (or <code>bss</code>) section
|
||
|
|
and can be multiply “defined”. Using the <code>section</code> attribute
|
||
|
|
changes what section the variable goes into and may cause the
|
||
|
|
linker to issue an error if an uninitialized variable has multiple
|
||
|
|
definitions. You can force a variable to be initialized with the
|
||
|
|
<samp>-fno-common</samp> flag or the <code>nocommon</code> attribute.
|
||
|
|
</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>tls_model ("<var>tls_model</var>")</code></dt>
|
||
|
|
<dd><a name="index-tls_005fmodel-variable-attribute"></a>
|
||
|
|
<p>The <code>tls_model</code> attribute sets thread-local storage model
|
||
|
|
(see <a href="Thread_002dLocal.html#Thread_002dLocal">Thread-Local</a>) of a particular <code>__thread</code> variable,
|
||
|
|
overriding <samp>-ftls-model=</samp> command-line switch on a per-variable
|
||
|
|
basis.
|
||
|
|
The <var>tls_model</var> argument should be one of <code>global-dynamic</code>,
|
||
|
|
<code>local-dynamic</code>, <code>initial-exec</code> or <code>local-exec</code>.
|
||
|
|
</p>
|
||
|
|
<p>Not all targets support this attribute.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>unused</code></dt>
|
||
|
|
<dd><a name="index-unused-variable-attribute"></a>
|
||
|
|
<p>This attribute, attached to a variable, means that the variable is meant
|
||
|
|
to be possibly unused. GCC does not produce a warning for this
|
||
|
|
variable.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>used</code></dt>
|
||
|
|
<dd><a name="index-used-variable-attribute"></a>
|
||
|
|
<p>This attribute, attached to a variable with static storage, means that
|
||
|
|
the variable must be emitted even if it appears that the variable is not
|
||
|
|
referenced.
|
||
|
|
</p>
|
||
|
|
<p>When applied to a static data member of a C++ class template, the
|
||
|
|
attribute also means that the member is instantiated if the
|
||
|
|
class itself is instantiated.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>vector_size (<var>bytes</var>)</code></dt>
|
||
|
|
<dd><a name="index-vector_005fsize-variable-attribute"></a>
|
||
|
|
<p>This attribute specifies the vector size for the variable, measured in
|
||
|
|
bytes. For example, the declaration:
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample">int foo __attribute__ ((vector_size (16)));
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>causes the compiler to set the mode for <code>foo</code>, to be 16 bytes,
|
||
|
|
divided into <code>int</code> sized units. Assuming a 32-bit int (a vector of
|
||
|
|
4 units of 4 bytes), the corresponding mode of <code>foo</code> is V4SI.
|
||
|
|
</p>
|
||
|
|
<p>This attribute is only applicable to integral and float scalars,
|
||
|
|
although arrays, pointers, and function return values are allowed in
|
||
|
|
conjunction with this construct.
|
||
|
|
</p>
|
||
|
|
<p>Aggregates with this attribute are invalid, even if they are of the same
|
||
|
|
size as a corresponding scalar. For example, the declaration:
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample">struct S { int a; };
|
||
|
|
struct S __attribute__ ((vector_size (16))) foo;
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>is invalid even if the size of the structure is the same as the size of
|
||
|
|
the <code>int</code>.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>visibility ("<var>visibility_type</var>")</code></dt>
|
||
|
|
<dd><a name="index-visibility-variable-attribute"></a>
|
||
|
|
<p>This attribute affects the linkage of the declaration to which it is attached.
|
||
|
|
The <code>visibility</code> attribute is described in
|
||
|
|
<a href="Common-Function-Attributes.html#Common-Function-Attributes">Common Function Attributes</a>.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>weak</code></dt>
|
||
|
|
<dd><a name="index-weak-variable-attribute"></a>
|
||
|
|
<p>The <code>weak</code> attribute is described in
|
||
|
|
<a href="Common-Function-Attributes.html#Common-Function-Attributes">Common Function Attributes</a>.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<hr>
|
||
|
|
<div class="header">
|
||
|
|
<p>
|
||
|
|
Next: <a href="AVR-Variable-Attributes.html#AVR-Variable-Attributes" accesskey="n" rel="next">AVR Variable Attributes</a>, Up: <a href="Variable-Attributes.html#Variable-Attributes" accesskey="u" rel="up">Variable 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>
|