[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
6.36 Specifying Attributes of Variables
The keyword __attribute__
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 section Declaring Attributes of Functions) and for types (see section Specifying Attributes of Types).
Other front ends might define more attributes
(see section Extensions to the C++ Language).
You may also specify attributes with ‘__’ 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 __aligned__
instead of aligned
.
See section Attribute Syntax, for details of the exact syntax for using attributes.
aligned (alignment)
This attribute specifies a minimum alignment for the variable or structure field, measured in bytes. For example, the declaration:
int x __attribute__ ((aligned (16))) = 0;
causes the compiler to allocate the global variable
x
on a 16-byte boundary. On a 68040, this could be used in conjunction with anasm
expression to access themove16
instruction which requires 16-byte aligned operands.You can also specify the alignment of structure fields. For example, to create a double-word aligned
int
pair, you could write:struct foo { int x[2] __attribute__ ((aligned (8))); };
This is an alternative to creating a union with a
double
member, which forces the union to be double-word aligned.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.
GCC also provides a target specific macro
__BIGGEST_ALIGNMENT__
, which is the largest alignment ever used for any data type on the target machine you are compiling for. For example, you could write:short array[3] __attribute__ ((aligned (__BIGGEST_ALIGNMENT__)));
The compiler automatically sets the alignment for the declared variable or field to
__BIGGEST_ALIGNMENT__
. 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__BIGGEST_ALIGNMENT__
may change depending on command-line options.When used on a struct, or struct member, the
aligned
attribute can only increase the alignment; in order to decrease it, thepacked
attribute must be specified as well. When used as part of a typedef, thealigned
attribute can both increase and decrease alignment, and specifying thepacked
attribute generates a warning.Note that the effectiveness of
aligned
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 specifyingaligned(16)
in an__attribute__
still only provides you with 8-byte alignment. See your linker documentation for further information.The
aligned
attribute can also be used for functions (see section Declaring Attributes of Functions.)cleanup (cleanup_function)
-
The
cleanup
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.If ‘-fexceptions’ is enabled, then cleanup_function is run during the stack unwinding that happens during the processing of the exception. Note that the
cleanup
attribute does not allow the exception to be caught, only to perform an action. It is undefined what happens if cleanup_function does not return normally. common
nocommon
-
The
common
attribute requests GCC to place a variable in “common” storage. Thenocommon
attribute requests the opposite—to allocate space for it directly.These attributes override the default chosen by the ‘-fno-common’ and ‘-fcommon’ flags respectively.
deprecated
deprecated (msg)
-
The
deprecated
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:extern int old_var __attribute__ ((deprecated)); extern int old_var; int new_fn () { return old_var; }
results in a warning on line 3 but not line 2. The optional msg argument, which must be a string, is printed in the warning if present.
The
deprecated
attribute can also be used for functions and types (see section Declaring Attributes of Functions, see section Specifying Attributes of Types.) mode (mode)
-
This attribute specifies the data type for the declaration—whichever type corresponds to the mode mode. This in effect lets you request an integer or floating-point type according to its width.
You may also specify a mode of
byte
or__byte__
to indicate the mode corresponding to a one-byte integer,word
or__word__
for the mode of a one-word integer, andpointer
or__pointer__
for the mode used to represent pointers. packed
-
The
packed
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 thealigned
attribute.Here is a structure in which the field
x
is packed, so that it immediately followsa
:struct foo { char a; int x[2] __attribute__ ((packed)); };
Note: The 4.1, 4.2 and 4.3 series of GCC ignore the
packed
attribute on bit-fields of typechar
. This has been fixed in GCC 4.4 but the change can lead to differences in the structure layout. See the documentation of ‘-Wpacked-bitfield-compat’ for more information. section ("section-name")
-
Normally, the compiler places the objects it generates in sections like
data
andbss
. Sometimes, however, you need additional sections, or you need certain particular variables to appear in special sections, for example to map to special hardware. Thesection
attribute specifies that a variable (or function) lives in a particular section. For example, this small program uses several specific section names: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() { /* Initialize stack pointer */ init_sp (stack + sizeof (stack)); /* Initialize initialized data */ memcpy (&init_data, &data, &edata - &data); /* Turn on the serial ports */ init_duart (&a); init_duart (&b); }
Use the
section
attribute with global variables and not local variables, as shown in the example.You may use the
section
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 thecommon
(orbss
) section and can be multiply “defined”. Using thesection
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 ‘-fno-common’ flag or thenocommon
attribute.Some file formats do not support arbitrary sections so the
section
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. shared
-
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
shared
and marking the section shareable:int foo __attribute__((section ("shared"), shared)) = 0; int main() { /* Read and write foo. All running copies see the same value. */ return 0; }
You may only use the
shared
attribute along withsection
attribute with a fully-initialized global definition because of the way linkers work. Seesection
attribute for more information.The
shared
attribute is only available on Microsoft Windows. tls_model ("tls_model")
-
The
tls_model
attribute sets thread-local storage model (see section Thread-Local Storage) of a particular__thread
variable, overriding ‘-ftls-model=’ command-line switch on a per-variable basis. The tls_model argument should be one ofglobal-dynamic
,local-dynamic
,initial-exec
orlocal-exec
.Not all targets support this attribute.
unused
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.
used
This attribute, attached to a variable, means that the variable must be emitted even if it appears that the variable is not referenced.
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.
vector_size (bytes)
This attribute specifies the vector size for the variable, measured in bytes. For example, the declaration:
int foo __attribute__ ((vector_size (16)));
causes the compiler to set the mode for
foo
, to be 16 bytes, divided intoint
sized units. Assuming a 32-bit int (a vector of 4 units of 4 bytes), the corresponding mode offoo
is V4SI.This attribute is only applicable to integral and float scalars, although arrays, pointers, and function return values are allowed in conjunction with this construct.
Aggregates with this attribute are invalid, even if they are of the same size as a corresponding scalar. For example, the declaration:
struct S { int a; }; struct S __attribute__ ((vector_size (16))) foo;
is invalid even if the size of the structure is the same as the size of the
int
.selectany
The
selectany
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 not to warn about size or content differences of the multiple definitions.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.
The
selectany
attribute is only available on Microsoft Windows targets. You can use__declspec (selectany)
as a synonym for__attribute__ ((selectany))
for compatibility with other compilers.weak
The
weak
attribute is described in Declaring Attributes of Functions.dllimport
The
dllimport
attribute is described in Declaring Attributes of Functions.dllexport
The
dllexport
attribute is described in Declaring Attributes of Functions.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This document was generated on October 19, 2013 using texi2html 5.0.