ePenguin
/
ePenguin-Software-Framework
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
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.
stable
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '5dd0775dc4'
${ noResults }
ePenguin-Software-Framework/toolchains/riscv/share/doc/gcc/Common-Variable-Attributes....

451 lines
20 KiB
HTML
Raw Normal View History Unescape Escape

added riscv64-unknown toolchain
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 Variable Attributes (Using the GNU Compiler Collection (GCC))</title>
<meta name="description" content="Common Variable Attributes (Using the GNU Compiler Collection (GCC))">
<meta name="keywords" content="Common Variable 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="Variable-Attributes.html#Variable-Attributes" rel="up" title="Variable Attributes">
<link href="ARC-Variable-Attributes.html#ARC-Variable-Attributes" rel="next" title="ARC 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.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-Variable-Attributes"></a>
<div class="header">
<p>
Next: <a href="ARC-Variable-Attributes.html#ARC-Variable-Attributes" accesskey="n" rel="next">ARC Variable Attributes</a>, Up: <a href="Variable-Attributes.html#Variable-Attributes" accesskey="u" rel="up">Variable Attributes</a> &nbsp; [<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>
<a name="index-warn_005fif_005fnot_005faligned-variable-attribute"></a>
</dd>
<dt><code>warn_if_not_aligned (<var>alignment</var>)</code></dt>
<dd><p>This attribute specifies a threshold for the structure field, measured
in bytes. If the structure field is aligned below the threshold, a
warning will be issued. For example, the declaration:
</p>
<div class="smallexample">
<pre class="smallexample">struct foo
{
int i1;
int i2;
unsigned long long x __attribute__((warn_if_not_aligned(16)));
};
</pre></div>
<p>causes the compiler to issue an warning on <code>struct foo</code>, like
&lsquo;<samp>warning: alignment 8 of 'struct foo' is less than 16</samp>&rsquo;.
The compiler also issues a warning, like &lsquo;<samp>warning: 'x' offset
8 in 'struct foo' isn't aligned to 16</samp>&rsquo;, when the structure field has
the misaligned offset:
</p>
<div class="smallexample">
<pre class="smallexample">struct foo
{
int i1;
int i2;
unsigned long long x __attribute__((warn_if_not_aligned(16)));
} __attribute__((aligned(16)));
</pre></div>
<p>This warning can be disabled by <samp>-Wno-if-not-aligned</samp>.
The <code>warn_if_not_aligned</code> attribute can also be used for types
(see <a href="Common-Type-Attributes.html#Common-Type-Attributes">Common Type 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
&ldquo;common&rdquo; storage. The <code>nocommon</code> attribute requests the
opposite&mdash;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>nonstring</code></dt>
<dd><a name="index-nonstring-variable-attribute"></a>
<p>The <code>nonstring</code> variable attribute specifies that an object or member
declaration with type array of <code>char</code>, <code>signed char</code>, or
<code>unsigned char</code>, or pointer to such a type is intended to store
character arrays that do not necessarily contain a terminating <code>NUL</code>.
This is useful in detecting uses of such arrays or pointers with functions
that expect <code>NUL</code>-terminated strings, and to avoid warnings when such
an array or pointer is used as an argument to a bounded string manipulation
function such as <code>strncpy</code>. For example, without the attribute, GCC
will issue a warning for the <code>strncpy</code> call below because it may
truncate the copy without appending the terminating <code>NUL</code> character.
Using the attribute makes it possible to suppress the warning. However,
when the array is declared with the attribute the call to <code>strlen</code> is
diagnosed because when the array doesn&rsquo;t contain a <code>NUL</code>-terminated
string the call is undefined. To copy, compare, of search non-string
character arrays use the <code>memcpy</code>, <code>memcmp</code>, <code>memchr</code>,
and other functions that operate on arrays of bytes. In addition,
calling <code>strnlen</code> and <code>strndup</code> with such arrays is safe
provided a suitable bound is specified, and not diagnosed.
</p>
<div class="smallexample">
<pre class="smallexample">struct Data
{
char name [32] __attribute__ ((nonstring));
};
int f (struct Data *pd, const char *s)
{
strncpy (pd-&gt;name, s, sizeof pd-&gt;name);
&hellip;
return strlen (pd-&gt;name); // unsafe, gets a warning
}
</pre></div>
</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&mdash;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>See <a href="http://gcc.gnu.org/onlinedocs/gccint/Machine-Modes.html#Machine-Modes">Machine Modes</a> in <cite>GNU Compiler Collection (GCC) Internals</cite>,
for a list of the possible keywords for <var>mode</var>.
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&mdash;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 (&quot;<var>section-name</var>&quot;)</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 (&quot;DUART_A&quot;))) = { 0 };
struct duart b __attribute__ ((section (&quot;DUART_B&quot;))) = { 0 };
char stack[10000] __attribute__ ((section (&quot;STACK&quot;))) = { 0 };
int init_data __attribute__ ((section (&quot;INITDATA&quot;)));
main()
{
/* <span class="roman">Initialize stack pointer</span> */
init_sp (stack + sizeof (stack));
/* <span class="roman">Initialize initialized data</span> */
memcpy (&amp;init_data, &amp;data, &amp;edata - &amp;data);
/* <span class="roman">Turn on the serial ports</span> */
init_duart (&amp;a);
init_duart (&amp;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 &ldquo;defined&rdquo;. 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 (&quot;<var>tls_model</var>&quot;)</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 (&quot;<var>visibility_type</var>&quot;)</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="ARC-Variable-Attributes.html#ARC-Variable-Attributes" accesskey="n" rel="next">ARC Variable Attributes</a>, Up: <a href="Variable-Attributes.html#Variable-Attributes" accesskey="u" rel="up">Variable Attributes</a> &nbsp; [<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>