Google Git
Sign in
android-kvm / toolchains / linux-x86 / gcc / fed620776f0e84cb3f4428b51ebf7e04618da707 / . / aarch64-linux-gnu-4.9 / share / doc / gcc / Variable-Attributes.html
blob: 381ec3a619142a6b7dd1f4dc575265d08726d4a6 [file] [log] [blame]
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Copyright (C) 1988-2015 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): Variable Attributes</title>
<meta name="description" content="Using the GNU Compiler Collection (GCC): Variable Attributes">
<meta name="keywords" content="Using the GNU Compiler Collection (GCC): 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="C-Extensions.html#C-Extensions" rel="up" title="C Extensions">
<link href="Type-Attributes.html#Type-Attributes" rel="next" title="Type Attributes">
<link href="Character-Escapes.html#Character-Escapes" rel="prev" title="Character Escapes">
<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="Variable-Attributes"></a>
<div class="header">
<p>
Next: <a href="Type-Attributes.html#Type-Attributes" accesskey="n" rel="next">Type Attributes</a>, Previous: <a href="Character-Escapes.html#Character-Escapes" accesskey="p" rel="prev">Character Escapes</a>, Up: <a href="C-Extensions.html#C-Extensions" accesskey="u" rel="up">C Extensions</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="Specifying-Attributes-of-Variables"></a>
<h3 class="section">6.36 Specifying Attributes of Variables</h3>
<a name="index-attribute-of-variables"></a>
<a name="index-variable-attributes"></a>
<p>The keyword <code>__attribute__</code> allows you to specify special
attributes of variables or structure fields. This keyword is followed
by an attribute specification inside double parentheses. Some
attributes are currently defined generically for variables.
Other attributes are defined for variables on particular target
systems. Other attributes are available for functions
(see <a href="Function-Attributes.html#Function-Attributes">Function Attributes</a>) and for types (see <a href="Type-Attributes.html#Type-Attributes">Type Attributes</a>).
Other front ends might define more attributes
(see <a href="C_002b_002b-Extensions.html#C_002b_002b-Extensions">Extensions to the C++ Language</a>).
</p>
<p>You may also specify attributes with &lsquo;<samp>__</samp>&rsquo; preceding and following
each keyword. This allows you to use them in header files without
being concerned about a possible macro of the same name. For example,
you may use <code>__aligned__</code> instead of <code>aligned</code>.
</p>
<p>See <a href="Attribute-Syntax.html#Attribute-Syntax">Attribute Syntax</a>, for details of the exact syntax for using
attributes.
</p>
<dl compact="compact">
<dd><a name="index-aligned-attribute-1"></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="Function-Attributes.html#Function-Attributes">Function Attributes</a>.)
</p>
</dd>
<dt><code>cleanup (<var>cleanup_function</var>)</code></dt>
<dd><a name="index-cleanup-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-attribute"></a>
<a name="index-nocommon-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-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="Function-Attributes.html#Function-Attributes">Function Attributes</a>, see <a href="Type-Attributes.html#Type-Attributes">Type Attributes</a>.)
</p>
</dd>
<dt><code>mode (<var>mode</var>)</code></dt>
<dd><a name="index-mode-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>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-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>shared</code></dt>
<dd><a name="index-shared-variable-attribute"></a>
<p>On Microsoft Windows, in addition to putting variable definitions in a named
section, the section can also be shared among all running copies of an
executable or DLL. For example, this small program defines shared data
by putting it in a named section <code>shared</code> and marking the section
shareable:
</p>
<div class="smallexample">
<pre class="smallexample">int foo __attribute__((section (&quot;shared&quot;), shared)) = 0;
int
main()
{
/* <span class="roman">Read and write foo. All running
copies see the same value.</span> */
return 0;
}
</pre></div>
<p>You may only use the <code>shared</code> attribute along with <code>section</code>
attribute with a fully-initialized global definition because of the way
linkers work. See <code>section</code> attribute for more information.
</p>
<p>The <code>shared</code> attribute is only available on Microsoft Windows.
</p>
</dd>
<dt><code>tls_model (&quot;<var>tls_model</var>&quot;)</code></dt>
<dd><a name="index-tls_005fmodel-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><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><p>This attribute, attached to a variable with the 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><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>selectany</code></dt>
<dd><p>The <code>selectany</code> attribute causes an initialized global variable to
have link-once semantics. When multiple definitions of the variable are
encountered by the linker, the first is selected and the remainder are
discarded. Following usage by the Microsoft compiler, the linker is told
<em>not</em> to warn about size or content differences of the multiple
definitions.
</p>
<p>Although the primary usage of this attribute is for POD types, the
attribute can also be applied to global C++ objects that are initialized
by a constructor. In this case, the static initialization and destruction
code for the object is emitted in each translation defining the object,
but the calls to the constructor and destructor are protected by a
link-once guard variable.
</p>
<p>The <code>selectany</code> attribute is only available on Microsoft Windows
targets. You can use <code>__declspec (selectany)</code> as a synonym for
<code>__attribute__ ((selectany))</code> for compatibility with other
compilers.
</p>
</dd>
<dt><code>weak</code></dt>
<dd><p>The <code>weak</code> attribute is described in <a href="Function-Attributes.html#Function-Attributes">Function Attributes</a>.
</p>
</dd>
<dt><code>dllimport</code></dt>
<dd><p>The <code>dllimport</code> attribute is described in <a href="Function-Attributes.html#Function-Attributes">Function Attributes</a>.
</p>
</dd>
<dt><code>dllexport</code></dt>
<dd><p>The <code>dllexport</code> attribute is described in <a href="Function-Attributes.html#Function-Attributes">Function Attributes</a>.
</p>
</dd>
</dl>
<a name="AVR-Variable-Attributes"></a><a name="AVR-Variable-Attributes-1"></a>
<h4 class="subsection">6.36.1 AVR Variable Attributes</h4>
<dl compact="compact">
<dt><code>progmem</code></dt>
<dd><a name="index-progmem-AVR-variable-attribute"></a>
<p>The <code>progmem</code> attribute is used on the AVR to place read-only
data in the non-volatile program memory (flash). The <code>progmem</code>
attribute accomplishes this by putting respective variables into a
section whose name starts with <code>.progmem</code>.
</p>
<p>This attribute works similar to the <code>section</code> attribute
but adds additional checking. Notice that just like the
<code>section</code> attribute, <code>progmem</code> affects the location
of the data but not how this data is accessed.
</p>
<p>In order to read data located with the <code>progmem</code> attribute
(inline) assembler must be used.
</p><div class="smallexample">
<pre class="smallexample">/* Use custom macros from <a href="http://nongnu.org/avr-libc/user-manual/">AVR-LibC</a><!-- /@w --> */
#include &lt;avr/pgmspace.h&gt;
/* Locate var in flash memory */
const int var[2] PROGMEM = { 1, 2 };
int read_var (int i)
{
/* Access var[] by accessor macro from avr/pgmspace.h */
return (int) pgm_read_word (&amp; var[i]);
}
</pre></div>
<p>AVR is a Harvard architecture processor and data and read-only data
normally resides in the data memory (RAM).
</p>
<p>See also the <a href="Named-Address-Spaces.html#AVR-Named-Address-Spaces">AVR Named Address Spaces</a> section for
an alternate way to locate and access data in flash memory.
</p></dd>
</dl>
<a name="Blackfin-Variable-Attributes"></a>
<h4 class="subsection">6.36.2 Blackfin Variable Attributes</h4>
<p>Three attributes are currently defined for the Blackfin.
</p>
<dl compact="compact">
<dt><code>l1_data</code></dt>
<dt><code>l1_data_A</code></dt>
<dt><code>l1_data_B</code></dt>
<dd><a name="index-l1_005fdata-variable-attribute"></a>
<a name="index-l1_005fdata_005fA-variable-attribute"></a>
<a name="index-l1_005fdata_005fB-variable-attribute"></a>
<p>Use these attributes on the Blackfin to place the variable into L1 Data SRAM.
Variables with <code>l1_data</code> attribute are put into the specific section
named <code>.l1.data</code>. Those with <code>l1_data_A</code> attribute are put into
the specific section named <code>.l1.data.A</code>. Those with <code>l1_data_B</code>
attribute are put into the specific section named <code>.l1.data.B</code>.
</p>
</dd>
<dt><code>l2</code></dt>
<dd><a name="index-l2-variable-attribute"></a>
<p>Use this attribute on the Blackfin to place the variable into L2 SRAM.
Variables with <code>l2</code> attribute are put into the specific section
named <code>.l2.data</code>.
</p></dd>
</dl>
<a name="M32R_002fD-Variable-Attributes"></a>
<h4 class="subsection">6.36.3 M32R/D Variable Attributes</h4>
<p>One attribute is currently defined for the M32R/D.
</p>
<dl compact="compact">
<dt><code>model (<var>model-name</var>)</code></dt>
<dd><a name="index-variable-addressability-on-the-M32R_002fD"></a>
<p>Use this attribute on the M32R/D to set the addressability of an object.
The identifier <var>model-name</var> is one of <code>small</code>, <code>medium</code>,
or <code>large</code>, representing each of the code models.
</p>
<p>Small model objects live in the lower 16MB of memory (so that their
addresses can be loaded with the <code>ld24</code> instruction).
</p>
<p>Medium and large model objects may live anywhere in the 32-bit address space
(the compiler generates <code>seth/add3</code> instructions to load their
addresses).
</p></dd>
</dl>
<a name="MeP-Variable-Attributes"></a><a name="MeP-Variable-Attributes-1"></a>
<h4 class="subsection">6.36.4 MeP Variable Attributes</h4>
<p>The MeP target has a number of addressing modes and busses. The
<code>near</code> space spans the standard memory space&rsquo;s first 16 megabytes
(24 bits). The <code>far</code> space spans the entire 32-bit memory space.
The <code>based</code> space is a 128-byte region in the memory space that
is addressed relative to the <code>$tp</code> register. The <code>tiny</code>
space is a 65536-byte region relative to the <code>$gp</code> register. In
addition to these memory regions, the MeP target has a separate 16-bit
control bus which is specified with <code>cb</code> attributes.
</p>
<dl compact="compact">
<dt><code>based</code></dt>
<dd><p>Any variable with the <code>based</code> attribute is assigned to the
<code>.based</code> section, and is accessed with relative to the
<code>$tp</code> register.
</p>
</dd>
<dt><code>tiny</code></dt>
<dd><p>Likewise, the <code>tiny</code> attribute assigned variables to the
<code>.tiny</code> section, relative to the <code>$gp</code> register.
</p>
</dd>
<dt><code>near</code></dt>
<dd><p>Variables with the <code>near</code> attribute are assumed to have addresses
that fit in a 24-bit addressing mode. This is the default for large
variables (<code>-mtiny=4</code> is the default) but this attribute can
override <code>-mtiny=</code> for small variables, or override <code>-ml</code>.
</p>
</dd>
<dt><code>far</code></dt>
<dd><p>Variables with the <code>far</code> attribute are addressed using a full
32-bit address. Since this covers the entire memory space, this
allows modules to make no assumptions about where variables might be
stored.
</p>
</dd>
<dt><code>io</code></dt>
<dt><code>io (<var>addr</var>)</code></dt>
<dd><p>Variables with the <code>io</code> attribute are used to address
memory-mapped peripherals. If an address is specified, the variable
is assigned that address, else it is not assigned an address (it is
assumed some other module assigns an address). Example:
</p>
<div class="smallexample">
<pre class="smallexample">int timer_count __attribute__((io(0x123)));
</pre></div>
</dd>
<dt><code>cb</code></dt>
<dt><code>cb (<var>addr</var>)</code></dt>
<dd><p>Variables with the <code>cb</code> attribute are used to access the control
bus, using special instructions. <code>addr</code> indicates the control bus
address. Example:
</p>
<div class="smallexample">
<pre class="smallexample">int cpu_clock __attribute__((cb(0x123)));
</pre></div>
</dd>
</dl>
<a name="i386-Variable-Attributes"></a><a name="i386-Variable-Attributes-1"></a>
<h4 class="subsection">6.36.5 i386 Variable Attributes</h4>
<p>Two attributes are currently defined for i386 configurations:
<code>ms_struct</code> and <code>gcc_struct</code>
</p>
<dl compact="compact">
<dt><code>ms_struct</code></dt>
<dt><code>gcc_struct</code></dt>
<dd><a name="index-ms_005fstruct-attribute"></a>
<a name="index-gcc_005fstruct-attribute"></a>
<p>If <code>packed</code> is used on a structure, or if bit-fields are used,
it may be that the Microsoft ABI lays out the structure differently
than the way GCC normally does. Particularly when moving packed
data between functions compiled with GCC and the native Microsoft compiler
(either via function call or as data in a file), it may be necessary to access
either format.
</p>
<p>Currently <samp>-m[no-]ms-bitfields</samp> is provided for the Microsoft Windows X86
compilers to match the native Microsoft compiler.
</p>
<p>The Microsoft structure layout algorithm is fairly simple with the exception
of the bit-field packing.
The padding and alignment of members of structures and whether a bit-field
can straddle a storage-unit boundary are determine by these rules:
</p>
<ol>
<li> Structure members are stored sequentially in the order in which they are
declared: the first member has the lowest memory address and the last member
the highest.
</li><li> Every data object has an alignment requirement. The alignment requirement
for all data except structures, unions, and arrays is either the size of the
object or the current packing size (specified with either the
<code>aligned</code> attribute or the <code>pack</code> pragma),
whichever is less. For structures, unions, and arrays,
the alignment requirement is the largest alignment requirement of its members.
Every object is allocated an offset so that:
<div class="smallexample">
<pre class="smallexample">offset % alignment_requirement == 0
</pre></div>
</li><li> Adjacent bit-fields are packed into the same 1-, 2-, or 4-byte allocation
unit if the integral types are the same size and if the next bit-field fits
into the current allocation unit without crossing the boundary imposed by the
common alignment requirements of the bit-fields.
</li></ol>
<p>MSVC interprets zero-length bit-fields in the following ways:
</p>
<ol>
<li> If a zero-length bit-field is inserted between two bit-fields that
are normally coalesced, the bit-fields are not coalesced.
<p>For example:
</p>
<div class="smallexample">
<pre class="smallexample">struct
{
unsigned long bf_1 : 12;
unsigned long : 0;
unsigned long bf_2 : 12;
} t1;
</pre></div>
<p>The size of <code>t1</code> is 8 bytes with the zero-length bit-field. If the
zero-length bit-field were removed, <code>t1</code>&rsquo;s size would be 4 bytes.
</p>
</li><li> If a zero-length bit-field is inserted after a bit-field, <code>foo</code>, and the
alignment of the zero-length bit-field is greater than the member that follows it,
<code>bar</code>, <code>bar</code> is aligned as the type of the zero-length bit-field.
<p>For example:
</p>
<div class="smallexample">
<pre class="smallexample">struct
{
char foo : 4;
short : 0;
char bar;
} t2;
struct
{
char foo : 4;
short : 0;
double bar;
} t3;
</pre></div>
<p>For <code>t2</code>, <code>bar</code> is placed at offset 2, rather than offset 1.
Accordingly, the size of <code>t2</code> is 4. For <code>t3</code>, the zero-length
bit-field does not affect the alignment of <code>bar</code> or, as a result, the size
of the structure.
</p>
<p>Taking this into account, it is important to note the following:
</p>
<ol>
<li> If a zero-length bit-field follows a normal bit-field, the type of the
zero-length bit-field may affect the alignment of the structure as whole. For
example, <code>t2</code> has a size of 4 bytes, since the zero-length bit-field follows a
normal bit-field, and is of type short.
</li><li> Even if a zero-length bit-field is not followed by a normal bit-field, it may
still affect the alignment of the structure:
<div class="smallexample">
<pre class="smallexample">struct
{
char foo : 6;
long : 0;
} t4;
</pre></div>
<p>Here, <code>t4</code> takes up 4 bytes.
</p></li></ol>
</li><li> Zero-length bit-fields following non-bit-field members are ignored:
<div class="smallexample">
<pre class="smallexample">struct
{
char foo;
long : 0;
char bar;
} t5;
</pre></div>
<p>Here, <code>t5</code> takes up 2 bytes.
</p></li></ol>
</dd>
</dl>
<a name="PowerPC-Variable-Attributes"></a>
<h4 class="subsection">6.36.6 PowerPC Variable Attributes</h4>
<p>Three attributes currently are defined for PowerPC configurations:
<code>altivec</code>, <code>ms_struct</code> and <code>gcc_struct</code>.
</p>
<p>For full documentation of the struct attributes please see the
documentation in <a href="#i386-Variable-Attributes">i386 Variable Attributes</a>.
</p>
<p>For documentation of <code>altivec</code> attribute please see the
documentation in <a href="Type-Attributes.html#PowerPC-Type-Attributes">PowerPC Type Attributes</a>.
</p>
<a name="SPU-Variable-Attributes"></a>
<h4 class="subsection">6.36.7 SPU Variable Attributes</h4>
<p>The SPU supports the <code>spu_vector</code> attribute for variables. For
documentation of this attribute please see the documentation in
<a href="Type-Attributes.html#SPU-Type-Attributes">SPU Type Attributes</a>.
</p>
<a name="Xstormy16-Variable-Attributes"></a>
<h4 class="subsection">6.36.8 Xstormy16 Variable Attributes</h4>
<p>One attribute is currently defined for xstormy16 configurations:
<code>below100</code>.
</p>
<dl compact="compact">
<dt><code>below100</code></dt>
<dd><a name="index-below100-attribute"></a>
<p>If a variable has the <code>below100</code> attribute (<code>BELOW100</code> is
allowed also), GCC places the variable in the first 0x100 bytes of
memory and use special opcodes to access it. Such variables are
placed in either the <code>.bss_below100</code> section or the
<code>.data_below100</code> section.
</p>
</dd>
</dl>
<hr>
<div class="header">
<p>
Next: <a href="Type-Attributes.html#Type-Attributes" accesskey="n" rel="next">Type Attributes</a>, Previous: <a href="Character-Escapes.html#Character-Escapes" accesskey="p" rel="prev">Character Escapes</a>, Up: <a href="C-Extensions.html#C-Extensions" accesskey="u" rel="up">C Extensions</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>