This is the mail archive of the
gcc-patches@gcc.gnu.org
mailing list for the GCC project.
[doc, committed] more attribute documentation cleanup
- From: Sandra Loosemore <sandra at codesourcery dot com>
- To: GCC Patches <gcc-patches at gcc dot gnu dot org>
- Date: Fri, 1 May 2015 21:48:24 -0600
- Subject: [doc, committed] more attribute documentation cleanup
- Authentication-results: sourceware.org; auth=none
I've checked in another installment of my ongoing cleanup of the
attribute documentation in extend.texi. In this patch, I've tidied up
the variable and type attribute sections. There's not much actual
change to the document text here, mostly just moving things around and
tweaking structure. These two sections were in much better shape
(besides being much shorter) than the function attribute section was
that I tackled in my last patch.
Next I am planning to reorder the attribute sections within the chapter
to group them together, and re-work the introductory material so that
the presentation flows better.
-Sandra
2015-05-01 Sandra Loosemore <sandra@codesourcery.com>
gcc/
* doc/extend.texi (Variable Attributes): Add menu and proper
@nodes to subsections. Move Microsoft Windows attributes to
their own subsection.
(Type Attributes): Reorganize introduction to remove duplicate
list of attributes. Add menu and proper @nodes to subsections.
Alphabetize the main table of common attributes.
Index: gcc/doc/extend.texi
===================================================================
--- gcc/doc/extend.texi (revision 222543)
+++ gcc/doc/extend.texi (working copy)
@@ -5400,6 +5400,26 @@ Other front ends might define more attri
@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})
@@ -5522,7 +5542,8 @@ argument, which must be a string, is pri
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
@@ -5608,33 +5629,6 @@ attribute is not available on all platfo
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
@@ -5692,45 +5686,14 @@ struct S __attribute__ ((vector_size (1
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
@@ -5813,6 +5776,7 @@ volatile int porta __attribute__((addres
@end table
+@node Blackfin Variable Attributes
@subsection Blackfin Variable Attributes
Three attributes are currently defined for the Blackfin.
@@ -5837,6 +5801,7 @@ Variables with @code{l2} attribute are p
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:
@@ -5865,6 +5830,7 @@ slightly under 32KB of data.
@end table
+@node IA-64 Variable Attributes
@subsection IA-64 Variable Attributes
The IA-64 back end supports the following variable attribute:
@@ -5883,6 +5849,7 @@ defined by shared libraries.
@end table
+@node M32R/D Variable Attributes
@subsection M32R/D Variable Attributes
One attribute is currently defined for the M32R/D@.
@@ -5903,7 +5870,7 @@ Medium and large model objects may live
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
@@ -5967,6 +5934,72 @@ int cpu_clock __attribute__((cb(0x123)))
@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:
@@ -5981,6 +6014,7 @@ documentation in @ref{x86 Variable Attri
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
@@ -5988,7 +6022,7 @@ The SPU supports the @code{spu_vector} a
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:
@@ -6126,6 +6160,7 @@ Here, @code{t5} takes up 2 bytes.
@end enumerate
@end table
+@node Xstormy16 Variable Attributes
@subsection Xstormy16 Variable Attributes
One attribute is currently defined for xstormy16 configurations:
@@ -6149,27 +6184,39 @@ placed in either the @code{.bss_below100
@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})
@@ -6250,14 +6297,6 @@ up to a maximum of 8-byte alignment, the
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
@@ -6289,78 +6328,38 @@ You may only specify this attribute on t
@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
@@ -6394,6 +6393,18 @@ present.
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
@@ -6435,70 +6446,107 @@ declaration, the above program would abo
@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
@@ -6524,7 +6572,7 @@ virtual table for @code{C} is not export
@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
@@ -6536,7 +6584,7 @@ Specifically, the @code{based}, @code{ti
@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:
@@ -6563,7 +6611,7 @@ __attribute__((altivec(bool__))) unsigne
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
@@ -6572,7 +6620,7 @@ allows one to declare vector data types
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: