gcc: Common Variable Attributes
1
1 6.32.1 Common Variable Attributes
1 ---------------------------------
1
1 The following attributes are supported on most targets.
1
1 'aligned (ALIGNMENT)'
1 This attribute specifies a minimum alignment for the variable or
1 structure field, measured in bytes. For example, the declaration:
1
1 int x __attribute__ ((aligned (16))) = 0;
1
1 causes the compiler to allocate the global variable 'x' on a
1 16-byte boundary. On a 68040, this could be used in conjunction
1 with an 'asm' expression to access the 'move16' instruction which
1 requires 16-byte aligned operands.
1
1 You can also specify the alignment of structure fields. For
1 example, to create a double-word aligned 'int' pair, you could
1 write:
1
1 struct foo { int x[2] __attribute__ ((aligned (8))); };
1
1 This is an alternative to creating a union with a 'double' member,
1 which forces the union to be double-word aligned.
1
1 As in the preceding examples, you can explicitly specify the
1 alignment (in bytes) that you wish the compiler to use for a given
1 variable or structure field. Alternatively, you can leave out the
1 alignment factor and just ask the compiler to align a variable or
1 field to the default alignment for the target architecture you are
1 compiling for. The default alignment is sufficient for all scalar
1 types, but may not be enough for all vector types on a target that
1 supports vector operations. The default alignment is fixed for a
1 particular target ABI.
1
1 GCC also provides a target specific macro '__BIGGEST_ALIGNMENT__',
1 which is the largest alignment ever used for any data type on the
1 target machine you are compiling for. For example, you could
1 write:
1
1 short array[3] __attribute__ ((aligned (__BIGGEST_ALIGNMENT__)));
1
1 The compiler automatically sets the alignment for the declared
1 variable or field to '__BIGGEST_ALIGNMENT__'. Doing this can often
1 make copy operations more efficient, because the compiler can use
1 whatever instructions copy the biggest chunks of memory when
1 performing copies to or from the variables or fields that you have
1 aligned this way. Note that the value of '__BIGGEST_ALIGNMENT__'
1 may change depending on command-line options.
1
1 When used on a struct, or struct member, the 'aligned' attribute
1 can only increase the alignment; in order to decrease it, the
1 'packed' attribute must be specified as well. When used as part of
1 a typedef, the 'aligned' attribute can both increase and decrease
1 alignment, and specifying the 'packed' attribute generates a
1 warning.
1
1 Note that the effectiveness of 'aligned' attributes may be limited
1 by inherent limitations in your linker. On many systems, the
1 linker is only able to arrange for variables to be aligned up to a
1 certain maximum alignment. (For some linkers, the maximum
1 supported alignment may be very very small.) If your linker is
1 only able to align variables up to a maximum of 8-byte alignment,
1 then specifying 'aligned(16)' in an '__attribute__' still only
1 provides you with 8-byte alignment. See your linker documentation
1 for further information.
1
11 The 'aligned' attribute can also be used for functions (⇒
Common Function Attributes.)
1
1 'warn_if_not_aligned (ALIGNMENT)'
1 This attribute specifies a threshold for the structure field,
1 measured in bytes. If the structure field is aligned below the
1 threshold, a warning will be issued. For example, the declaration:
1
1 struct foo
1 {
1 int i1;
1 int i2;
1 unsigned long long x __attribute__((warn_if_not_aligned(16)));
1 };
1
1 causes the compiler to issue an warning on 'struct foo', like
1 'warning: alignment 8 of 'struct foo' is less than 16'. The
1 compiler also issues a warning, like 'warning: 'x' offset 8 in
1 'struct foo' isn't aligned to 16', when the structure field has the
1 misaligned offset:
1
1 struct foo
1 {
1 int i1;
1 int i2;
1 unsigned long long x __attribute__((warn_if_not_aligned(16)));
1 } __attribute__((aligned(16)));
1
1 This warning can be disabled by '-Wno-if-not-aligned'. The
11 'warn_if_not_aligned' attribute can also be used for types (⇒
Common Type Attributes.)
1
1 'cleanup (CLEANUP_FUNCTION)'
1 The 'cleanup' attribute runs a function when the variable goes out
1 of scope. This attribute can only be applied to auto function
1 scope variables; it may not be applied to parameters or variables
1 with static storage duration. The function must take one
1 parameter, a pointer to a type compatible with the variable. The
1 return value of the function (if any) is ignored.
1
1 If '-fexceptions' is enabled, then CLEANUP_FUNCTION is run during
1 the stack unwinding that happens during the processing of the
1 exception. Note that the 'cleanup' attribute does not allow the
1 exception to be caught, only to perform an action. It is undefined
1 what happens if CLEANUP_FUNCTION does not return normally.
1
1 'common'
1 'nocommon'
1 The 'common' attribute requests GCC to place a variable in "common"
1 storage. The 'nocommon' attribute requests the opposite--to
1 allocate space for it directly.
1
1 These attributes override the default chosen by the '-fno-common'
1 and '-fcommon' flags respectively.
1
1 'deprecated'
1 'deprecated (MSG)'
1 The 'deprecated' attribute results in a warning if the variable is
1 used anywhere in the source file. This is useful when identifying
1 variables that are expected to be removed in a future version of a
1 program. The warning also includes the location of the declaration
1 of the deprecated variable, to enable users to easily find further
1 information about why the variable is deprecated, or what they
1 should do instead. Note that the warning only occurs for uses:
1
1 extern int old_var __attribute__ ((deprecated));
1 extern int old_var;
1 int new_fn () { return old_var; }
1
1 results in a warning on line 3 but not line 2. The optional MSG
1 argument, which must be a string, is printed in the warning if
1 present.
1
1 The 'deprecated' attribute can also be used for functions and types
DONTPRINTYET 1 (⇒Common Function Attributes, *noteCommon Type
1DONTPRINTYET 1 (⇒Common Function Attributes, ⇒Common Type
Attributes).
1
1 'nonstring'
1 The 'nonstring' variable attribute specifies that an object or
1 member declaration with type array of 'char', 'signed char', or
1 'unsigned char', or pointer to such a type is intended to store
1 character arrays that do not necessarily contain a terminating
1 'NUL'. This is useful in detecting uses of such arrays or pointers
1 with functions that expect 'NUL'-terminated strings, and to avoid
1 warnings when such an array or pointer is used as an argument to a
1 bounded string manipulation function such as 'strncpy'. For
1 example, without the attribute, GCC will issue a warning for the
1 'strncpy' call below because it may truncate the copy without
1 appending the terminating 'NUL' character. Using the attribute
1 makes it possible to suppress the warning. However, when the array
1 is declared with the attribute the call to 'strlen' is diagnosed
1 because when the array doesn't contain a 'NUL'-terminated string
1 the call is undefined. To copy, compare, of search non-string
1 character arrays use the 'memcpy', 'memcmp', 'memchr', and other
1 functions that operate on arrays of bytes. In addition, calling
1 'strnlen' and 'strndup' with such arrays is safe provided a
1 suitable bound is specified, and not diagnosed.
1
1 struct Data
1 {
1 char name [32] __attribute__ ((nonstring));
1 };
1
1 int f (struct Data *pd, const char *s)
1 {
1 strncpy (pd->name, s, sizeof pd->name);
1 ...
1 return strlen (pd->name); // unsafe, gets a warning
1 }
1
1 'mode (MODE)'
1 This attribute specifies the data type for the
1 declaration--whichever type corresponds to the mode MODE. This in
1 effect lets you request an integer or floating-point type according
1 to its width.
1
1 ⇒(gccint)Machine Modes, for a list of the possible keywords
1 for MODE. You may also specify a mode of 'byte' or '__byte__' to
1 indicate the mode corresponding to a one-byte integer, 'word' or
1 '__word__' for the mode of a one-word integer, and 'pointer' or
1 '__pointer__' for the mode used to represent pointers.
1
1 'packed'
1 The 'packed' attribute specifies that a variable or structure field
1 should have the smallest possible alignment--one byte for a
1 variable, and one bit for a field, unless you specify a larger
1 value with the 'aligned' attribute.
1
1 Here is a structure in which the field 'x' is packed, so that it
1 immediately follows 'a':
1
1 struct foo
1 {
1 char a;
1 int x[2] __attribute__ ((packed));
1 };
1
1 _Note:_ The 4.1, 4.2 and 4.3 series of GCC ignore the 'packed'
1 attribute on bit-fields of type 'char'. This has been fixed in GCC
1 4.4 but the change can lead to differences in the structure layout.
1 See the documentation of '-Wpacked-bitfield-compat' for more
1 information.
1
1 'section ("SECTION-NAME")'
1 Normally, the compiler places the objects it generates in sections
1 like 'data' and 'bss'. Sometimes, however, you need additional
1 sections, or you need certain particular variables to appear in
1 special sections, for example to map to special hardware. The
1 'section' attribute specifies that a variable (or function) lives
1 in a particular section. For example, this small program uses
1 several specific section names:
1
1 struct duart a __attribute__ ((section ("DUART_A"))) = { 0 };
1 struct duart b __attribute__ ((section ("DUART_B"))) = { 0 };
1 char stack[10000] __attribute__ ((section ("STACK"))) = { 0 };
1 int init_data __attribute__ ((section ("INITDATA")));
1
1 main()
1 {
1 /* Initialize stack pointer */
1 init_sp (stack + sizeof (stack));
1
1 /* Initialize initialized data */
1 memcpy (&init_data, &data, &edata - &data);
1
1 /* Turn on the serial ports */
1 init_duart (&a);
1 init_duart (&b);
1 }
1
1 Use the 'section' attribute with _global_ variables and not _local_
1 variables, as shown in the example.
1
1 You may use the 'section' attribute with initialized or
1 uninitialized global variables but the linker requires each object
1 be defined once, with the exception that uninitialized variables
1 tentatively go in the 'common' (or 'bss') section and can be
1 multiply "defined". Using the 'section' attribute changes what
1 section the variable goes into and may cause the linker to issue an
1 error if an uninitialized variable has multiple definitions. You
1 can force a variable to be initialized with the '-fno-common' flag
1 or the 'nocommon' attribute.
1
1 Some file formats do not support arbitrary sections so the
1 'section' attribute is not available on all platforms. If you need
1 to map the entire contents of a module to a particular section,
1 consider using the facilities of the linker instead.
1
1 'tls_model ("TLS_MODEL")'
11 The 'tls_model' attribute sets thread-local storage model (⇒
Thread-Local) of a particular '__thread' variable, overriding
1 '-ftls-model=' command-line switch on a per-variable basis. The
1 TLS_MODEL argument should be one of 'global-dynamic',
1 'local-dynamic', 'initial-exec' or 'local-exec'.
1
1 Not all targets support this attribute.
1
1 'unused'
1 This attribute, attached to a variable, means that the variable is
1 meant to be possibly unused. GCC does not produce a warning for
1 this variable.
1
1 'used'
1 This attribute, attached to a variable with static storage, means
1 that the variable must be emitted even if it appears that the
1 variable is not referenced.
1
1 When applied to a static data member of a C++ class template, the
1 attribute also means that the member is instantiated if the class
1 itself is instantiated.
1
1 'vector_size (BYTES)'
1 This attribute specifies the vector size for the variable, measured
1 in bytes. For example, the declaration:
1
1 int foo __attribute__ ((vector_size (16)));
1
1 causes the compiler to set the mode for 'foo', to be 16 bytes,
1 divided into 'int' sized units. Assuming a 32-bit int (a vector of
1 4 units of 4 bytes), the corresponding mode of 'foo' is V4SI.
1
1 This attribute is only applicable to integral and float scalars,
1 although arrays, pointers, and function return values are allowed
1 in conjunction with this construct.
1
1 Aggregates with this attribute are invalid, even if they are of the
1 same size as a corresponding scalar. For example, the declaration:
1
1 struct S { int a; };
1 struct S __attribute__ ((vector_size (16))) foo;
1
1 is invalid even if the size of the structure is the same as the
1 size of the 'int'.
1
1 'visibility ("VISIBILITY_TYPE")'
1 This attribute affects the linkage of the declaration to which it
11 is attached. The 'visibility' attribute is described in ⇒
Common Function Attributes.
1
1 'weak'
11 The 'weak' attribute is described in ⇒Common Function
Attributes.
1