Now that GCC's default language dialect for both C and C++ includes
support for the standard attribute syntax, we should encourage users
to prefer that instead of the legacy GNU syntax, while recognizing
that there is a lot of code out there using the latter. This patch
updates the discussion in the introduction to the Attributes section
with examples showing attribute placement in both syntaxes and focuses
the syntax section on the GNU syntax only. (Users can read the C/C++
standards, programming books or tutorials, etc to learn about the
standard syntax, so we don't need to document that in detail.)
gcc/ChangeLog
PR c++/102397
* gcc/doc/extend.texi (Attributes): Rewrite and expand discussion
of standard vs legacy syntax, with several examples.
(Attribute Syntax): Rename section to...
(GNU Attribute Syntax): ...this. Prune discussion of standard
attribute syntax. Fix cross-references.
---
gcc/doc/extend.texi | 198 +++++++++++++++++++++++++++++++++++---------
1 file changed, 160 insertions(+), 38 deletions(-)
diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
index 5e481126069..901201aa3d9 100644
--- a/gcc/doc/extend.texi
+++ b/gcc/doc/extend.texi
@@ -1633,12 +1633,145 @@ are documented in this section.
GCC provides two different ways to specify attributes: the traditional
GNU syntax using @samp{__attribute__ ((...))} annotations, and the
newer standard C and C++ syntax using @samp{[[...]]} with the
-@samp{gnu::} namespace prefix on attribute names.
-The traditional syntax, described in detail in @ref{Attribute Syntax},
-is supported in all non-strict C and C++ language dialects.
-The standard syntax is supported in C with @option{-std=c23} or later,
-in C++ with @option{-std=c++11} or later, and as an extension in older
-GNU C and C++ dialects.
+@samp{gnu::} namespace prefix on attribute names. Both syntaxes are
+accepted in all supported C and C++ dialects. However, if you use the
+@option{-Wpedantic} option (@pxref{Warning Options}), GCC warns about
+uses of the standard attribute syntax in C dialects prior to C23 and
+C++ dialects prior to C++11, which did not include this feature. You
+can suppress these warnings by prefixing the attribute name with the
+@code{__extension__} keyword; @xref{Alternate Keywords}.
+
+The traditional syntax is described in detail in @ref{GNU Attribute Syntax}.
+Refer to the C or C++ standards for the exact rules regarding placement
+of standard attributes.
+
+Here are some examples showing the use of attributes.
+
+No matter which syntax is used, attributes in a variable declaration can be
+placed at the beginning of the declaration (in which case they apply
+to all declarators in the declaration), or after a particular
+declarator (applying only to that variable).
+
+@smallexample
+[[gnu::aligned (16)]] int v1 = 0;
+int v2 __attribute__ ((aligned (16))) = 0;
+int v3 [[gnu::aligned (16)]] = 0;
+int v4 __attribute__ ((aligned (16))) = 0;
+@end smallexample
+
+@cindex function attributes
+@cindex declaring attributes of functions
+Attributes for a function declaration or definition can appear first
+in both syntaxes:
+
+@smallexample
+[[gnu::section ("bar")]] extern void f1 (void);
+__attribute__ ((section ("bar"))) extern void f2 (void);
+@end smallexample
+
+@noindent
+But, watch out for the common style of placing of attributes after
+the argument list when using the GNU syntax. With the standard
+syntax, attributes in this location are treated as modifying the
+@emph{type} of the function rather than the function itself, or its
+name.
+
+@smallexample
+extern void f3 (void) [[gnu::section ("bar")]]; /* Error! */
+extern void f4 (void) __attribute__ ((section ("bar")));
+@end smallexample
+
+@noindent
+An error is diagnosed on the declaration of @code{f3} because the
+@code{section} attribute can't apply to types. To apply it correctly
+to the function, either put the attribute at the beginning of the
+declaration, or put it after the name of the function, like this:
+
+@smallexample
+extern void f3 [[gnu::section ("bar")]] (void);
+@end smallexample
+
+Typedefs follow the same attribute placement rules for other as other
+declarations. These declarations are all valid with similiar meanings.
+
+@smallexample
+[[gnu::unavailable]] typedef int *t1;
+typedef int *t2 [[gnu::unavailable]];
+__attribute__ ((unavailable)) typedef int *t3;
+typedef int *t4 __attribute__ ((unavailable));
+@end smallexample
+
+Members of a struct, union, or C++ class follow similar rules for
+attribute placement as other declarations, but beware that many
+attributes intended for use in top-level declarations, such as those
+that specify linker attributes of symbols, do not make sense here.
+
+Put attributes that apply to a @code{struct}, @code{union}, @code{class}, or
+@code{enum} type as a whole between the keyword and the type name:
+
+@smallexample
+struct [[gnu::aligned (8)]] s1 @{ short f[3]; @};
+struct __attribute__ ((aligned (8))) s2 @{ short f[3]; @};
+@end smallexample
+
+There are only a few attributes that apply to enumerators; those are
+placed directly after the enumerator name.
+
+Statement attributes are placed before a statement or label. An
+attribute placed before an empty statement is a special case, an
+@dfn{attribute declaration}, with semantics that depend on the
+particular attribute. Otherwise statement attributes usually apply to
+the statement or label they prefix.
+
+These two functions are equivalent:
+
+@smallexample
+int foo1 (int x, int y)
+@{
+ [[gnu::assume (x == 42)]];
+ return x + y;
+@}
+
+int foo2 (int x, int y)
+@{
+ __attribute__((assume(x == 42)));
+ return x + y;
+@}
+@end smallexample
+
+If you want to specify multiple attributes on the same entity, both
+syntaxes allow you to to list them in the same attribute specifier,
+separated by commas:
+
+@smallexample
+[[gnu::section ("bar"), gnu::weak]]
+void g1 (void) @{ f1 (); @}
+
+__attribute__ ((section ("bar"), weak))
+void g2 (void) @{ f2 (); @}
+@end smallexample
+
+@noindent
+Alternatively, you can use multiple attribute specifiers:
+
+@smallexample
+[[gnu::section ("bar")]] [[gnu::weak]]
+void g3 (void) @{ f1 (); @}
+
+__attribute__ ((section ("bar"))) __attribute__ ((weak))
+void g4 (void) @{ f2 (); @}
+@end smallexample
+
+Compatible attribute specifications on distinct declarations
+of the same entity are merged. An attribute specification that is not
+compatible with attributes already applied to a declaration of the same
+entity is ignored with a warning.
+
+Every GNU-specific attribute has an alternate name that is prefixed
+and suffixed by two underscores; for example, the alternate name of
+@code{weak} is @code{__weak__}. These alternate names are useful in
+library header files in case they are included into files that have
+redefined the base name of the attribute as a preprocessor macro.
@menu
* Function Attributes:: Declaring that functions have no side effects,
@@ -1648,7 +1781,7 @@ GNU C and C++ dialects.
* Label Attributes:: Specifying attributes on labels.
* Enumerator Attributes:: Specifying attributes on enumerators.
* Statement Attributes:: Specifying attributes on statements.
-* Attribute Syntax:: Formal syntax for attributes.
+* GNU Attribute Syntax:: Formal syntax for attributes.
@end menu
@node Function Attributes
@@ -1679,7 +1812,7 @@ GNU syntax using @samp{__attribute__ ((...))}
annotations, and the
newer standard C and C++ syntax using @samp{[[...]]} with the
@samp{gnu::} prefix on attribute names. Note that the exact rules for
placement of attributes in your source code are different depending on
-which syntax you use. @xref{Attribute Syntax}, for details.
+which syntax you use. @xref{GNU Attribute Syntax}, for details.
Compatible attribute specifications on distinct declarations
of the same function are merged. An attribute specification that is not
@@ -1756,7 +1889,16 @@ GCC plugins may provide their own attributes.
@node Common Function Attributes
@subsubsection Common Function Attributes
-The following attributes are supported on most targets.
+The following GNU-specific attributes are supported on most targets in
+both C and C++. When using the standard syntax, you must prefix their
+names with @samp{gnu::}, such as @code{gnu::section}.
+
+@xref{C++ Attributes}, for additional GNU attributes that are specific
+to C++.
+
+With the @option{-fopenmp} option, GCC additionally recognizes OpenMP
+directives, with names prefixed with @samp{omp::}, using the standard
+@samp{[[]]} syntax. @xref{OpenMP}.
@table @code
@c Keep this table alphabetized by attribute name. Treat _ as space.
@@ -7327,7 +7469,7 @@ GNU syntax using @samp{__attribute__ ((...))}
annotations, and the
newer standard C and C++ syntax using @samp{[[...]]} with the
@samp{gnu::} prefix on attribute names. Note that the exact rules for
placement of attributes in your source code are different depending on
-which syntax you use. @xref{Attribute Syntax}, for details.
+which syntax you use. @xref{GNU Attribute Syntax}, for details.
@menu
* Common Variable Attributes::
@@ -8577,7 +8719,7 @@ GNU syntax using @samp{__attribute__ ((...))}
annotations, and the
newer standard C and C++ syntax using @samp{[[...]]} with the
@samp{gnu::} prefix on attribute names. Note that the exact rules for
placement of attributes in your source code are different depending on
-which syntax you use. @xref{Attribute Syntax}, for details.
+which syntax you use. @xref{GNU Attribute Syntax}, for details.
You may specify type attributes in an enum, struct or union type
declaration or definition by placing them immediately after the
@@ -9609,7 +9751,7 @@ attributes on variables.
@subsection Label Attributes
@cindex Label Attributes
-GCC allows attributes to be set on C labels. @xref{Attribute Syntax}, for
+GCC allows attributes to be set on C labels. @xref{GNU Attribute Syntax}, for
details of the exact syntax for using attributes. Other attributes are
available for functions (@pxref{Function Attributes}), variables
(@pxref{Variable Attributes}), enumerators (@pxref{Enumerator Attributes}),
@@ -9665,7 +9807,7 @@ with computed goto or @code{asm goto}.
@subsection Enumerator Attributes
@cindex Enumerator Attributes
-GCC allows attributes to be set on enumerators. @xref{Attribute Syntax}, for
+GCC allows attributes to be set on enumerators. @xref{GNU Attribute Syntax},
for
details of the exact syntax for using attributes. Other attributes are
available for functions (@pxref{Function Attributes}), variables
(@pxref{Variable Attributes}), labels (@pxref{Label Attributes}), statements
@@ -9710,7 +9852,7 @@ same manner as the @code{deprecated} attribute.
@subsection Statement Attributes
@cindex Statement Attributes
-GCC allows attributes to be set on statements. @xref{Attribute Syntax},
+GCC allows attributes to be set on statements. @xref{GNU Attribute Syntax},
for details of the exact syntax for using attributes. Other attributes are
available for functions (@pxref{Function Attributes}), variables
(@pxref{Variable Attributes}), labels (@pxref{Label Attributes}), enumerators
@@ -9858,8 +10000,8 @@ variable is a function argument, because those are in
scope
for the whole function.
@end table
-@node Attribute Syntax
-@subsection Attribute Syntax
+@node GNU Attribute Syntax
+@subsection GNU Attribute Syntax
@cindex attribute syntax
@cindex C standard attributes
@cindex C++ standard attributes
@@ -9870,27 +10012,7 @@ GCC provides two different ways to specify attributes:
the standard C
and C++ syntax using double square brackets, and the older GNU
extension syntax using the @code{@w{__attribute__}} keyword, which predates
the adoption of the standard syntax and is still widely used in older
-code.
-
-The standard @samp{[[]]} attribute syntax is recognized by GCC's
-default language dialect for both C and C++. More specifically, this
-syntax was first introduced in the C++11 language standard
-(@pxref{Standards}), and is supported by GCC in C++ code with
-@option{-std=c++11} or @option{-std=gnu++11} or later. It is also
-part of the C23 language standard and is supported when compiling C
-code with @option{-std=c23} or @option{-std=gnu17} or later.
-
-When using GNU-specific attributes in the standard syntax, you must
-prefix their names with @samp{gnu::}, such as @code{gnu::section}.
-Refer to the relevant language standards for exact details on the
-placement of @samp{[[]]} attributes within your code, as they differ
-in some details from the rules for the GNU attribute syntax.
-
-With the @option{-fopenmp} option, GCC additionally recognizes OpenMP
-directives, with names prefixed with @samp{omp::}, using the standard
-@samp{[[]]} syntax. @xref{OpenMP}.
-
-The remainder of this section describes the details of the GNU extension
+code. This section describes the details of the GNU extension
@code{__attribute__} syntax,
and the constructs to which attribute specifiers bind, for the C
language. Some details may vary for C++ and Objective-C@. Because of
@@ -17854,7 +17976,7 @@ restrictions as the argument to @code{typeof}
(@pxref{Typeof}). The
@var{attribute} argument is an attribute name optionally followed by
a comma-separated list of arguments enclosed in parentheses. Both forms
of attribute names---with and without double leading and trailing
-underscores---are recognized. @xref{Attribute Syntax}, for details.
+underscores---are recognized. @xref{GNU Attribute Syntax}, for details.
When no attribute arguments are specified for an attribute that expects
one or more arguments the function returns @code{true} if
@var{type-or-expression} has been declared with the attribute regardless
--
2.39.5
