diff options
Diffstat (limited to 'gcc/doc')
| -rw-r--r-- | gcc/doc/extend.texi | 62 | ||||
| -rw-r--r-- | gcc/doc/invoke.texi | 91 |
2 files changed, 146 insertions, 7 deletions
diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi index 96fed15..fcf86d3 100644 --- a/gcc/doc/extend.texi +++ b/gcc/doc/extend.texi @@ -60,6 +60,7 @@ extensions, accepted by GCC in C90 mode and in C++. * Type Attributes:: Specifying attributes of types. * Label Attributes:: Specifying attributes on labels. * Enumerator Attributes:: Specifying attributes on enumerators. +* Statement Attributes:: Specifying attributes on statements. * Attribute Syntax:: Formal syntax for attributes. * Function Prototypes:: Prototype declarations and old-style definitions. * C++ Comments:: C++ comments are recognized. @@ -2261,6 +2262,7 @@ GCC also supports attributes on variable declarations (@pxref{Variable Attributes}), labels (@pxref{Label Attributes}), enumerators (@pxref{Enumerator Attributes}), +statements (@pxref{Statement Attributes}), and types (@pxref{Type Attributes}). There is some overlap between the purposes of attributes and pragmas @@ -5558,8 +5560,8 @@ attributes are currently defined generically for variables. Other attributes are defined for variables on particular target systems. Other attributes are available for functions (@pxref{Function Attributes}), labels (@pxref{Label Attributes}), -enumerators (@pxref{Enumerator Attributes}), and for types -(@pxref{Type Attributes}). +enumerators (@pxref{Enumerator Attributes}), statements +(@pxref{Statement Attributes}), and for types (@pxref{Type Attributes}). Other front ends might define more attributes (@pxref{C++ Extensions,,Extensions to the C++ Language}). @@ -6340,7 +6342,8 @@ 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}), enumerators (@pxref{Enumerator Attributes}), and for +Attributes}), enumerators (@pxref{Enumerator Attributes}), +statements (@pxref{Statement Attributes}), and for variables (@pxref{Variable Attributes}). The @code{__attribute__} keyword is followed by an attribute specification @@ -6850,7 +6853,8 @@ GCC allows attributes to be set on C labels. @xref{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}), -and for types (@pxref{Type Attributes}). +statements (@pxref{Statement Attributes}), and for types +(@pxref{Type Attributes}). This example uses the @code{cold} label attribute to indicate the @code{ErrorHandling} branch is unlikely to be taken and that the @@ -6903,8 +6907,8 @@ with computed goto or @code{asm goto}. GCC allows attributes to be set on enumerators. @xref{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}), -and for types (@pxref{Type Attributes}). +(@pxref{Variable Attributes}), labels (@pxref{Label Attributes}), statements +(@pxref{Statement Attributes}), and for types (@pxref{Type Attributes}). This example uses the @code{deprecated} enumerator attribute to indicate the @code{oldval} enumerator is deprecated: @@ -6935,6 +6939,46 @@ do instead. Note that the warnings only occurs for uses. @end table +@node Statement Attributes +@section Statement Attributes +@cindex Statement Attributes + +GCC allows attributes to be set on null statements. @xref{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 +(@pxref{Enumerator Attributes}), and for types (@pxref{Type Attributes}). + +This example uses the @code{fallthrough} statement attribute to indicate that +the @option{-Wimplicit-fallthrough} warning should not be emitted: + +@smallexample +switch (cond) + @{ + case 1: + bar (1); + __attribute__((fallthrough)); + case 2: + @dots{} + @} +@end smallexample + +@table @code +@item fallthrough +@cindex @code{fallthrough} statement attribute +The @code{fallthrough} attribute with a null statement serves as a +fallthrough statement. It hints to the compiler that a statement +that falls through to another case label, or user-defined label +in a switch statement is intentional and thus the +@option{-Wimplicit-fallthrough} warning must not trigger. The +fallthrough attribute may appear at most once in each attribute +list, and may not be mixed with other attributes. It can only +be used in a switch statement (the compiler will issue an error +otherwise), after a preceding statement and before a logically +succeeding case label, or user-defined label. + +@end table + @node Attribute Syntax @section Attribute Syntax @cindex attribute syntax @@ -6962,6 +7006,8 @@ and enumerated types. applying to labels. @xref{Enumerator Attributes}, for details of the semantics of attributes applying to enumerators. +@xref{Statement Attributes}, for details of the semantics of attributes +applying to statements. An @dfn{attribute specifier} is of the form @code{__attribute__ ((@var{attribute-list}))}. An @dfn{attribute list} @@ -7027,6 +7073,10 @@ present. The optional attribute in the enumerator appertains to the enumeration constant. It is not possible to place the attribute after the constant expression, if present. +@subsubheading Statement Attributes +In GNU C, an attribute specifier list may appear as part of a null +statement. The attribute goes before the semicolon. + @subsubheading Type Attributes An attribute specifier list may appear as part of a @code{struct}, diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi index a5481b5..ce0eaef 100644 --- a/gcc/doc/invoke.texi +++ b/gcc/doc/invoke.texi @@ -273,7 +273,8 @@ Objective-C and Objective-C++ Dialects}. -Wformat-security -Wformat-signedness -Wformat-y2k -Wframe-address @gol -Wframe-larger-than=@var{len} -Wno-free-nonheap-object -Wjump-misses-init @gol -Wignored-qualifiers -Wignored-attributes -Wincompatible-pointer-types @gol --Wimplicit -Wimplicit-function-declaration -Wimplicit-int @gol +-Wimplicit -Wimplicit-fallthrough -Wimplicit-function-declaration @gol +-Wimplicit-int @gol -Winit-self -Winline -Wno-int-conversion -Wint-in-bool-context @gol -Wno-int-to-pointer-cast -Winvalid-memory-model -Wno-invalid-offsetof @gol -Winvalid-pch -Wlarger-than=@var{len} @gol @@ -3719,6 +3720,7 @@ name is still supported, but the newer name is more descriptive.) @gccoptlist{-Wclobbered @gol -Wempty-body @gol -Wignored-qualifiers @gol +-Wimplicit-fallthrough @gol -Wmissing-field-initializers @gol -Wmissing-parameter-type @r{(C only)} @gol -Wold-style-declaration @r{(C only)} @gol @@ -4087,6 +4089,93 @@ enabled by default and it is made into an error by Same as @option{-Wimplicit-int} and @option{-Wimplicit-function-declaration}. This warning is enabled by @option{-Wall}. +@item -Wimplicit-fallthrough +@opindex Wimplicit-fallthrough +@opindex Wno-implicit-fallthrough +Warn when a switch case falls through. For example: + +@smallexample +@group +switch (cond) + @{ + case 1: + a = 1; + break; + case 2: + a = 2; + case 3: + a = 3; + break; + @} +@end group +@end smallexample + +This warning does not warn when the last statement of a case cannot +fall through, e.g. when there is a return statement or a call to function +declared with the noreturn attribute. @option{-Wimplicit-fallthrough} +also takes into account control flow statements, such as ifs, and only +warns when appropriate. E.g.@: + +@smallexample +@group +switch (cond) + @{ + case 1: + if (i > 3) @{ + bar (5); + break; + @} else if (i < 1) @{ + bar (0); + @} else + return; + default: + @dots{} + @} +@end group +@end smallexample + +Since there are occasions where a switch case fall through is desirable, +GCC provides an attribute, @code{__attribute__ ((fallthrough))}, that is +to be used along with a null statement to suppress this warning that +would normally occur: + +@smallexample +@group +switch (cond) + @{ + case 1: + bar (0); + __attribute__ ((fallthrough)); + default: + @dots{} + @} +@end group +@end smallexample + +C++17 provides a standard way to suppress the @option{-Wimplicit-fallthrough} +warning using @code{[[fallthrough]];} instead of the GNU attribute. In C++11 +or C++14 users can use @code{[[gnu::fallthrough]];}, which is a GNU extension. +Instead of the these attributes, it is also possible to add a "falls through" +comment to silence the warning. GCC accepts a wide range of such comments, +for example all of "Falls through.", "fallthru", "FALLS-THROUGH" work. This +comment needs to consist of two words merely, optionally followed by periods +or whitespaces. + +@smallexample +@group +switch (cond) + @{ + case 1: + bar (0); + /* FALLTHRU */ + default: + @dots{} + @} +@end group +@end smallexample + +This warning is enabled by @option{-Wextra}. + @item -Wignored-qualifiers @r{(C and C++ only)} @opindex Wignored-qualifiers @opindex Wno-ignored-qualifiers |