@xref{Attribute Syntax}, for details of the exact syntax for using
attributes.
+@menu
+* Common Variable Attributes::
+* AVR Variable Attributes::
+* Blackfin Variable Attributes::
+* H8/300 Variable Attributes::
+* IA-64 Variable Attributes::
+* M32R/D Variable Attributes::
+* MeP Variable Attributes::
+* Microsoft Windows Variable Attributes::
+* PowerPC Variable Attributes::
+* SPU Variable Attributes::
+* x86 Variable Attributes::
+* Xstormy16 Variable Attributes::
+@end menu
+
+@node Common Variable Attributes
+@subsection Common Variable Attributes
+
+The following attributes are supported on most targets.
+
@table @code
@cindex @code{aligned} variable attribute
@item aligned (@var{alignment})
present.
The @code{deprecated} attribute can also be used for functions and
-types (@pxref{Common Function Attributes}, @pxref{Type Attributes}).
+types (@pxref{Common Function Attributes},
+@pxref{Common Type Attributes}).
@item mode (@var{mode})
@cindex @code{mode} variable attribute
If you need to map the entire contents of a module to a particular
section, consider using the facilities of the linker instead.
-@item shared
-@cindex @code{shared} variable attribute
-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} and marking the section
-shareable:
-
-@smallexample
-int foo __attribute__((section ("shared"), shared)) = 0;
-
-int
-main()
-@{
- /* @r{Read and write foo. All running
- copies see the same value.} */
- return 0;
-@}
-@end smallexample
-
-@noindent
-You may only use the @code{shared} attribute along with @code{section}
-attribute with a fully-initialized global definition because of the way
-linkers work. See @code{section} attribute for more information.
-
-The @code{shared} attribute is only available on Microsoft Windows@.
-
@item tls_model ("@var{tls_model}")
@cindex @code{tls_model} variable attribute
The @code{tls_model} attribute sets thread-local storage model
is invalid even if the size of the structure is the same as the size of
the @code{int}.
-@item selectany
-@cindex @code{selectany} variable attribute
-The @code{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
-@emph{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 @code{selectany} attribute is only available on Microsoft Windows
-targets. You can use @code{__declspec (selectany)} as a synonym for
-@code{__attribute__ ((selectany))} for compatibility with other
-compilers.
-
@item weak
@cindex @code{weak} variable attribute
The @code{weak} attribute is described in
@ref{Common Function Attributes}.
-@item dllimport
-@cindex @code{dllimport} variable attribute
-The @code{dllimport} attribute is described in
-@ref{Microsoft Windows Function Attributes}.
-
-@item dllexport
-@cindex @code{dllexport} variable attribute
-The @code{dllexport} attribute is described in
-@ref{Microsoft Windows Function Attributes}.
-
@end table
-@anchor{AVR Variable Attributes}
+@node AVR Variable Attributes
@subsection AVR Variable Attributes
@table @code
@end table
+@node Blackfin Variable Attributes
@subsection Blackfin Variable Attributes
Three attributes are currently defined for the Blackfin.
named @code{.l2.data}.
@end table
+@node H8/300 Variable Attributes
@subsection H8/300 Variable Attributes
These variable attributes are available for H8/300 targets:
@end table
+@node IA-64 Variable Attributes
@subsection IA-64 Variable Attributes
The IA-64 back end supports the following variable attribute:
@end table
+@node M32R/D Variable Attributes
@subsection M32R/D Variable Attributes
One attribute is currently defined for the M32R/D@.
addresses).
@end table
-@anchor{MeP Variable Attributes}
+@node MeP Variable Attributes
@subsection MeP Variable Attributes
The MeP target has a number of addressing modes and busses. The
@end table
+@node Microsoft Windows Variable Attributes
+@subsection Microsoft Windows Variable Attributes
+
+You can use these attributes on Microsoft Windows targets.
+@ref{x86 Variable Attributes} for additional Windows compatibility
+attributes available on all x86 targets.
+
+@table @code
+@item dllimport
+@itemx dllexport
+@cindex @code{dllimport} variable attribute
+@cindex @code{dllexport} variable attribute
+The @code{dllimport} and @code{dllexport} attributes are described in
+@ref{Microsoft Windows Function Attributes}.
+
+@item selectany
+@cindex @code{selectany} variable attribute
+The @code{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
+@emph{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 @code{selectany} attribute is only available on Microsoft Windows
+targets. You can use @code{__declspec (selectany)} as a synonym for
+@code{__attribute__ ((selectany))} for compatibility with other
+compilers.
+
+@item shared
+@cindex @code{shared} variable attribute
+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} and marking the section
+shareable:
+
+@smallexample
+int foo __attribute__((section ("shared"), shared)) = 0;
+
+int
+main()
+@{
+ /* @r{Read and write foo. All running
+ copies see the same value.} */
+ return 0;
+@}
+@end smallexample
+
+@noindent
+You may only use the @code{shared} attribute along with @code{section}
+attribute with a fully-initialized global definition because of the way
+linkers work. See @code{section} attribute for more information.
+
+The @code{shared} attribute is only available on Microsoft Windows@.
+
+@end table
+
+@node PowerPC Variable Attributes
@subsection PowerPC Variable Attributes
Three attributes currently are defined for PowerPC configurations:
For documentation of @code{altivec} attribute please see the
documentation in @ref{PowerPC Type Attributes}.
+@node SPU Variable Attributes
@subsection SPU Variable Attributes
@cindex @code{spu_vector} variable attribute, SPU
documentation of this attribute please see the documentation in
@ref{SPU Type Attributes}.
-@anchor{x86 Variable Attributes}
+@node x86 Variable Attributes
@subsection x86 Variable Attributes
Two attributes are currently defined for x86 configurations:
@end enumerate
@end table
+@node Xstormy16 Variable Attributes
@subsection Xstormy16 Variable Attributes
One attribute is currently defined for xstormy16 configurations:
@cindex type attributes
The keyword @code{__attribute__} allows you to specify special
-attributes of @code{struct} and @code{union} types when you define
-such types. This keyword is followed by an attribute specification
-inside double parentheses. Eight attributes are currently defined for
-types: @code{aligned}, @code{packed}, @code{transparent_union},
-@code{unused}, @code{deprecated}, @code{visibility}, @code{may_alias}
-and @code{bnd_variable_size}. Other attributes are defined for
+attributes of types. Some type attributes apply only to @code{struct}
+and @code{union} types, while others can apply to any type defined
+via a @code{typedef} declaration. Other attributes are defined for
functions (@pxref{Function Attributes}), labels (@pxref{Label
Attributes}) and for variables (@pxref{Variable Attributes}).
-You may specify type attributes in an enum, struct or union type
-declaration or definition, or for other types in a @code{typedef}
-declaration.
+The @code{__attribute__} keyword is followed by an attribute specification
+inside double parentheses.
-For an enum, struct or union type, you may specify attributes either
-between the enum, struct or union tag and the name of the type, or
-just past the closing curly brace of the @emph{definition}. The
-former syntax is preferred.
+You may specify type attributes in an enum, struct or union type
+declaration or definition by placing them immediately after the
+@code{struct}, @code{union} or @code{enum} keyword. A less preferred
+syntax is to place them just past the closing curly brace of the
+definition.
+You can also include type attributes in a @code{typedef} declaration.
@xref{Attribute Syntax}, for details of the exact syntax for using
attributes.
+@menu
+* Common Type Attributes::
+* ARM Type Attributes::
+* MeP Type Attributes::
+* PowerPC Type Attributes::
+* SPU Type Attributes::
+* x86 Type Attributes::
+@end menu
+
+@node Common Type Attributes
+@subsection Common Type Attributes
+
+The following type attributes are supported on most targets.
+
@table @code
@cindex @code{aligned} type attribute
@item aligned (@var{alignment})
in an @code{__attribute__} still only provides you with 8-byte
alignment. See your linker documentation for further information.
-@item packed
-@cindex @code{packed} type attribute
-This attribute, attached to @code{struct} or @code{union} type
-definition, specifies that each member (other than zero-width bit-fields)
-of the structure or union is placed to minimize the memory required. When
-attached to an @code{enum} definition, it indicates that the smallest
-integral type should be used.
-
@opindex fshort-enums
Specifying this attribute for @code{struct} and @code{union} types is
equivalent to specifying the @code{packed} attribute on each of the
@code{struct} or @code{union}, not on a @code{typedef} that does not
also define the enumerated type, structure or union.
-@item transparent_union
-@cindex @code{transparent_union} type attribute
-
-This attribute, attached to a @code{union} type definition, indicates
-that any function parameter having that union type causes calls to that
-function to be treated in a special way.
-
-First, the argument corresponding to a transparent union type can be of
-any type in the union; no cast is required. Also, if the union contains
-a pointer type, the corresponding argument can be a null pointer
-constant or a void pointer expression; and if the union contains a void
-pointer type, the corresponding argument can be any pointer expression.
-If the union member type is a pointer, qualifiers like @code{const} on
-the referenced type must be respected, just as with normal pointer
-conversions.
-
-Second, the argument is passed to the function using the calling
-conventions of the first member of the transparent union, not the calling
-conventions of the union itself. All members of the union must have the
-same machine representation; this is necessary for this argument passing
-to work properly.
-
-Transparent unions are designed for library functions that have multiple
-interfaces for compatibility reasons. For example, suppose the
-@code{wait} function must accept either a value of type @code{int *} to
-comply with POSIX, or a value of type @code{union wait *} to comply with
-the 4.1BSD interface. If @code{wait}'s parameter were @code{void *},
-@code{wait} would accept both kinds of arguments, but it would also
-accept any other pointer type and this would make argument type checking
-less useful. Instead, @code{<sys/wait.h>} might define the interface
-as follows:
-
-@smallexample
-typedef union __attribute__ ((__transparent_union__))
- @{
- int *__ip;
- union wait *__up;
- @} wait_status_ptr_t;
-
-pid_t wait (wait_status_ptr_t);
-@end smallexample
-
-@noindent
-This interface allows either @code{int *} or @code{union wait *}
-arguments to be passed, using the @code{int *} calling convention.
-The program can call @code{wait} with arguments of either type:
+@item bnd_variable_size
+@cindex @code{bnd_variable_size} type attribute
+@cindex Pointer Bounds Checker attributes
+When applied to a structure field, this attribute tells Pointer
+Bounds Checker that the size of this field should not be computed
+using static type information. It may be used to mark variably-sized
+static array fields placed at the end of a structure.
@smallexample
-int w1 () @{ int w; return wait (&w); @}
-int w2 () @{ union wait w; return wait (&w); @}
+struct S
+@{
+ int size;
+ char data[1];
+@}
+S *p = (S *)malloc (sizeof(S) + 100);
+p->data[10] = 0; //Bounds violation
@end smallexample
@noindent
-With this interface, @code{wait}'s implementation might look like this:
+By using an attribute for the field we may avoid unwanted bound
+violation checks:
@smallexample
-pid_t wait (wait_status_ptr_t p)
+struct S
@{
- return waitpid (-1, p.__ip, 0);
+ int size;
+ char data[1] __attribute__((bnd_variable_size));
@}
+S *p = (S *)malloc (sizeof(S) + 100);
+p->data[10] = 0; //OK
@end smallexample
-@item unused
-@cindex @code{unused} type attribute
-When attached to a type (including a @code{union} or a @code{struct}),
-this attribute means that variables of that type are meant to appear
-possibly unused. GCC does not produce a warning for any variables of
-that type, even if the variable appears to do nothing. This is often
-the case with lock or thread classes, which are usually defined and then
-not referenced, but contain constructors and destructors that have
-nontrivial bookkeeping functions.
-
@item deprecated
@itemx deprecated (@var{msg})
@cindex @code{deprecated} type attribute
The @code{deprecated} attribute can also be used for functions and
variables (@pxref{Function Attributes}, @pxref{Variable Attributes}.)
+@item designated_init
+@cindex @code{designated_init} type attribute
+This attribute may only be applied to structure types. It indicates
+that any initialization of an object of this type must use designated
+initializers rather than positional initializers. The intent of this
+attribute is to allow the programmer to indicate that a structure's
+layout may change, and that therefore relying on positional
+initialization will result in future breakage.
+
+GCC emits warnings based on this attribute by default; use
+@option{-Wno-designated-init} to suppress them.
+
@item may_alias
@cindex @code{may_alias} type attribute
Accesses through pointers to types with this attribute are not subject
@option{-fstrict-aliasing}, which is on by default at @option{-O2} or
above.
-@item visibility
-@cindex @code{visibility} type attribute
-In C++, attribute visibility (@pxref{Function Attributes}) can also be
-applied to class, struct, union and enum types. Unlike other type
-attributes, the attribute must appear between the initial keyword and
-the name of the type; it cannot appear after the body of the type.
+@item packed
+@cindex @code{packed} type attribute
+This attribute, attached to @code{struct} or @code{union} type
+definition, specifies that each member (other than zero-width bit-fields)
+of the structure or union is placed to minimize the memory required. When
+attached to an @code{enum} definition, it indicates that the smallest
+integral type should be used.
-Note that the type visibility is applied to vague linkage entities
-associated with the class (vtable, typeinfo node, etc.). In
-particular, if a class is thrown as an exception in one shared object
-and caught in another, the class must have default visibility.
-Otherwise the two shared objects are unable to use the same
-typeinfo node and exception handling will break.
+@item transparent_union
+@cindex @code{transparent_union} type attribute
-@item designated_init
-@cindex @code{designated_init} type attribute
-This attribute may only be applied to structure types. It indicates
-that any initialization of an object of this type must use designated
-initializers rather than positional initializers. The intent of this
-attribute is to allow the programmer to indicate that a structure's
-layout may change, and that therefore relying on positional
-initialization will result in future breakage.
+This attribute, attached to a @code{union} type definition, indicates
+that any function parameter having that union type causes calls to that
+function to be treated in a special way.
-GCC emits warnings based on this attribute by default; use
-@option{-Wno-designated-init} to suppress them.
+First, the argument corresponding to a transparent union type can be of
+any type in the union; no cast is required. Also, if the union contains
+a pointer type, the corresponding argument can be a null pointer
+constant or a void pointer expression; and if the union contains a void
+pointer type, the corresponding argument can be any pointer expression.
+If the union member type is a pointer, qualifiers like @code{const} on
+the referenced type must be respected, just as with normal pointer
+conversions.
-@item bnd_variable_size
-@cindex @code{bnd_variable_size} type attribute
-@cindex Pointer Bounds Checker attributes
-When applied to a structure field, this attribute tells Pointer
-Bounds Checker that the size of this field should not be computed
-using static type information. It may be used to mark variably-sized
-static array fields placed at the end of a structure.
+Second, the argument is passed to the function using the calling
+conventions of the first member of the transparent union, not the calling
+conventions of the union itself. All members of the union must have the
+same machine representation; this is necessary for this argument passing
+to work properly.
+
+Transparent unions are designed for library functions that have multiple
+interfaces for compatibility reasons. For example, suppose the
+@code{wait} function must accept either a value of type @code{int *} to
+comply with POSIX, or a value of type @code{union wait *} to comply with
+the 4.1BSD interface. If @code{wait}'s parameter were @code{void *},
+@code{wait} would accept both kinds of arguments, but it would also
+accept any other pointer type and this would make argument type checking
+less useful. Instead, @code{<sys/wait.h>} might define the interface
+as follows:
@smallexample
-struct S
-@{
- int size;
- char data[1];
-@}
-S *p = (S *)malloc (sizeof(S) + 100);
-p->data[10] = 0; //Bounds violation
+typedef union __attribute__ ((__transparent_union__))
+ @{
+ int *__ip;
+ union wait *__up;
+ @} wait_status_ptr_t;
+
+pid_t wait (wait_status_ptr_t);
@end smallexample
@noindent
-By using an attribute for the field we may avoid unwanted bound
-violation checks:
+This interface allows either @code{int *} or @code{union wait *}
+arguments to be passed, using the @code{int *} calling convention.
+The program can call @code{wait} with arguments of either type:
@smallexample
-struct S
+int w1 () @{ int w; return wait (&w); @}
+int w2 () @{ union wait w; return wait (&w); @}
+@end smallexample
+
+@noindent
+With this interface, @code{wait}'s implementation might look like this:
+
+@smallexample
+pid_t wait (wait_status_ptr_t p)
@{
- int size;
- char data[1] __attribute__((bnd_variable_size));
+ return waitpid (-1, p.__ip, 0);
@}
-S *p = (S *)malloc (sizeof(S) + 100);
-p->data[10] = 0; //OK
@end smallexample
+@item unused
+@cindex @code{unused} type attribute
+When attached to a type (including a @code{union} or a @code{struct}),
+this attribute means that variables of that type are meant to appear
+possibly unused. GCC does not produce a warning for any variables of
+that type, even if the variable appears to do nothing. This is often
+the case with lock or thread classes, which are usually defined and then
+not referenced, but contain constructors and destructors that have
+nontrivial bookkeeping functions.
+
+@item visibility
+@cindex @code{visibility} type attribute
+In C++, attribute visibility (@pxref{Function Attributes}) can also be
+applied to class, struct, union and enum types. Unlike other type
+attributes, the attribute must appear between the initial keyword and
+the name of the type; it cannot appear after the body of the type.
+
+Note that the type visibility is applied to vague linkage entities
+associated with the class (vtable, typeinfo node, etc.). In
+particular, if a class is thrown as an exception in one shared object
+and caught in another, the class must have default visibility.
+Otherwise the two shared objects are unable to use the same
+typeinfo node and exception handling will break.
+
@end table
To specify multiple attributes, separate them by commas within the
double parentheses: for example, @samp{__attribute__ ((aligned (16),
packed))}.
+@node ARM Type Attributes
@subsection ARM Type Attributes
@cindex @code{notshared} type attribute, ARM
@code{__attribute__} instead of @code{__declspec} if you prefer, but
most Symbian OS code uses @code{__declspec}.)
-@anchor{MeP Type Attributes}
+@node MeP Type Attributes
@subsection MeP Type Attributes
@cindex @code{based} type attribute, MeP
@code{far} attributes may be applied to either. The @code{io} and
@code{cb} attributes may not be applied to types.
-@anchor{PowerPC Type Attributes}
+@node PowerPC Type Attributes
@subsection PowerPC Type Attributes
Three attributes currently are defined for PowerPC configurations:
These attributes mainly are intended to support the @code{__vector},
@code{__pixel}, and @code{__bool} AltiVec keywords.
-@anchor{SPU Type Attributes}
+@node SPU Type Attributes
@subsection SPU Type Attributes
@cindex @code{spu_vector} type attribute, SPU
Language Extensions Specification. It is intended to support the
@code{__vector} keyword.
-@anchor{x86 Type Attributes}
+@node x86 Type Attributes
@subsection x86 Type Attributes
Two attributes are currently defined for x86 configurations:
projects / gcc.git / commitdiff