The following attributes are supported on most targets.
aligned (
alignment)
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 an asm
expression to access the move16
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, the packed
attribute must be specified as well. When used as part of a typedef, the aligned
attribute can both increase and decrease alignment, and specifying the packed
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 specifying aligned(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 Common Function Attributes.)
cleanup (
cleanup_function)
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
common
attribute requests GCC to place a variable in “common” storage. The nocommon
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)
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 Common Function Attributes, see Common Type Attributes).
mode (
mode)
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, and pointer
or __pointer__
for the mode used to represent pointers.
packed
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 the aligned
attribute. Here is a structure in which the field x
is packed, so that it immediately follows a
:
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 type char
. 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")
data
and bss
. 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 section
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 the common
(or bss
) section and can be multiply “defined”. Using the section
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 the nocommon
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.
tls_model ("
tls_model")
tls_model
attribute sets thread-local storage model (see Thread-Local) of a particular __thread
variable, overriding -ftls-model=
command-line switch on a per-variable basis. The tls_model argument should be one of global-dynamic
, local-dynamic
, initial-exec
or local-exec
. Not all targets support this attribute.
unused
used
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)
int foo __attribute__ ((vector_size (16)));
causes the compiler to set the mode for foo
, to be 16 bytes, divided into int
sized units. Assuming a 32-bit int (a vector of 4 units of 4 bytes), the corresponding mode of foo
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
.
visibility ("
visibility_type")
visibility
attribute is described in Common Function Attributes. weak
weak
attribute is described in Common Function Attributes.
© Free Software Foundation
Licensed under the GNU Free Documentation License, Version 1.3.
https://gcc.gnu.org/onlinedocs/gcc-6.3.0/gcc/Common-Variable-Attributes.html