From: Sandra Loosemore Date: Wed, 17 Jan 2024 21:37:19 +0000 (+0000) Subject: Clean up documentation for -Wstrict-flex-arrays [PR111659] X-Git-Tag: basepoints/gcc-15~1944 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=eb71695f76378151cb38372051bf50aed792f36d;p=thirdparty%2Fgcc.git Clean up documentation for -Wstrict-flex-arrays [PR111659] gcc/ChangeLog PR middle-end/111659 * doc/extend.texi (Common Variable Attributes): Fix long lines in documentation of strict_flex_array + other minor copy-editing. Add a cross-reference to -Wstrict-flex-arrays. * doc/invoke.texi (Option Summary): Fix whitespace in tables before -fstrict-flex-arrays and -Wstrict-flex-arrays. (C Dialect Options): Combine the docs for the two -fstrict-flex-arrays forms into a single entry. Note this option is for C/C++ only. Add a cross-reference to -Wstrict-flex-arrays. (Warning Options): Note -Wstrict-flex-arrays is for C/C++ only. Minor copy-editing. Add cross references to the strict_flex_array attribute and -fstrict-flex-arrays option. Add note that this option depends on -ftree-vrp. --- diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi index 89e823629e37..91f0b669b9e0 100644 --- a/gcc/doc/extend.texi +++ b/gcc/doc/extend.texi @@ -7790,18 +7790,24 @@ are treated as flexible array members. @var{level}=3 is the strictest level, only when the trailing array is declared as a flexible array member per C99 standard onwards (@samp{[]}), it is treated as a flexible array member. -There are two more levels in between 0 and 3, which are provided to support -older codes that use GCC zero-length array extension (@samp{[0]}) or one-element -array as flexible array members (@samp{[1]}): -When @var{level} is 1, the trailing array is treated as a flexible array member -when it is declared as either @samp{[]}, @samp{[0]}, or @samp{[1]}; -When @var{level} is 2, the trailing array is treated as a flexible array member -when it is declared as either @samp{[]}, or @samp{[0]}. - -This attribute can be used with or without the @option{-fstrict-flex-arrays}. -When both the attribute and the option present at the same time, the level of -the strictness for the specific trailing array field is determined by the -attribute. +There are two more levels in between 0 and 3, which are provided to +support older codes that use GCC zero-length array extension +(@samp{[0]}) or one-element array as flexible array members +(@samp{[1]}). When @var{level} is 1, the trailing array is treated as +a flexible array member when it is declared as either @samp{[]}, +@samp{[0]}, or @samp{[1]}; When @var{level} is 2, the trailing array +is treated as a flexible array member when it is declared as either +@samp{[]}, or @samp{[0]}. + +This attribute can be used with or without the +@option{-fstrict-flex-arrays} command-line option. When both the +attribute and the option are present at the same time, the level of +the strictness for the specific trailing array field is determined by +the attribute. + +The @code{strict_flex_array} attribute interacts with the +@option{-Wstrict-flex-arrays} option. @xref{Warning Options}, for more +information. @cindex @code{alloc_size} variable attribute @item alloc_size (@var{position}) diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi index 43fd3c3a3cdf..a537be667362 100644 --- a/gcc/doc/invoke.texi +++ b/gcc/doc/invoke.texi @@ -207,7 +207,7 @@ in the following sections. -fopenmp -fopenmp-simd -fopenmp-target-simd-clone@r{[}=@var{device-type}@r{]} -fpermitted-flt-eval-methods=@var{standard} -fplan9-extensions -fsigned-bitfields -funsigned-bitfields --fsigned-char -funsigned-char -fstrict-flex-arrays[=@var{n}] +-fsigned-char -funsigned-char -fstrict-flex-arrays[=@var{n}] -fsso-struct=@var{endianness}} @item C++ Language Options @@ -405,7 +405,7 @@ Objective-C and Objective-C++ Dialects}. -Wstrict-aliasing=n -Wstrict-overflow -Wstrict-overflow=@var{n} -Wstring-compare -Wno-stringop-overflow -Wno-stringop-overread --Wno-stringop-truncation -Wstrict-flex-arrays +-Wno-stringop-truncation -Wstrict-flex-arrays -Wsuggest-attribute=@r{[}pure@r{|}const@r{|}noreturn@r{|}format@r{|}malloc@r{]} -Wswitch -Wno-switch-bool -Wswitch-default -Wswitch-enum -Wno-switch-outside-range -Wno-switch-unreachable -Wsync-nand @@ -2945,22 +2945,22 @@ is always just like one of those two. @opindex fstrict-flex-arrays @opindex fno-strict-flex-arrays -@item -fstrict-flex-arrays -Control when to treat the trailing array of a structure as a flexible array -member for the purpose of accessing the elements of such an array. -The positive form is equivalent to @option{-fstrict-flex-arrays=3}, which is the -strictest. A trailing array is treated as a flexible array member only when it -is declared as a flexible array member per C99 standard onwards. -The negative form is equivalent to @option{-fstrict-flex-arrays=0}, which is the -least strict. All trailing arrays of structures are treated as flexible array -members. - @opindex fstrict-flex-arrays=@var{level} -@item -fstrict-flex-arrays=@var{level} +@item -fstrict-flex-arrays @r{(C and C++ only)} +@itemx -fstrict-flex-arrays=@var{level} @r{(C and C++ only)} Control when to treat the trailing array of a structure as a flexible array member for the purpose of accessing the elements of such an array. The value of @var{level} controls the level of strictness. +@option{-fstrict-flex-arrays} is equivalent to +@option{-fstrict-flex-arrays=3}, which is the strictest; all +trailing arrays of structures are treated as flexible array members. + +The negative form @option{-fno-strict-flex-arrays} is equivalent to +@option{-fstrict-flex-arrays=0}, which is the least strict. In this +case a trailing array is treated as a flexible array member only when +it is declared as a flexible array member per C99 standard onwards. + The possible values of @var{level} are the same as for the @code{strict_flex_array} attribute (@pxref{Variable Attributes}). @@ -2968,6 +2968,10 @@ You can control this behavior for a specific trailing array field of a structure by using the variable attribute @code{strict_flex_array} attribute (@pxref{Variable Attributes}). +The @option{-fstrict_flex_arrays} option interacts with the +@option{-Wstrict-flex-arrays} option. @xref{Warning Options}, for more +information. + @opindex fsso-struct @item -fsso-struct=@var{endianness} Set the default scalar storage order of structures and unions to the @@ -8161,28 +8165,31 @@ safe. @xref{Common Variable Attributes}. @opindex Wstrict-flex-arrays @opindex Wno-strict-flex-arrays -@item -Wstrict-flex-arrays -Warn about inproper usages of flexible array members +@item -Wstrict-flex-arrays @r{(C and C++ only)} +Warn about improper usages of flexible array members according to the @var{level} of the @code{strict_flex_array (@var{level})} attribute attached to the trailing array field of a structure if it's available, otherwise according to the @var{level} of the option -@option{-fstrict-flex-arrays=@var{level}}. +@option{-fstrict-flex-arrays=@var{level}}. @xref{Common Variable Attributes}, +for more information about the attribute, and @ref{C Dialect Options} for +more information about the option. @code{-Wstrict-flex-arrays} +is effective only when @var{level} is greater than 0. -This option is effective only when @var{level} is bigger than 0. Otherwise, -it will be ignored with a warning. - -when @var{level}=1, warnings will be issued for a trailing array reference +When @var{level}=1, warnings are issued for a trailing array reference of a structure that have 2 or more elements if the trailing array is referenced as a flexible array member. -when @var{level}=2, in addition to @var{level}=1, additional warnings will be +When @var{level}=2, in addition to @var{level}=1, additional warnings are issued for a trailing one-element array reference of a structure if the array is referenced as a flexible array member. -when @var{level}=3, in addition to @var{level}=2, additional warnings will be +When @var{level}=3, in addition to @var{level}=2, additional warnings are issued for a trailing zero-length array reference of a structure if the array is referenced as a flexible array member. +This option is more effective when @option{-ftree-vrp} is active (the +default for @option{-O2} and above) but some warnings may be diagnosed +even without optimization. @opindex Wsuggest-attribute= @opindex Wno-suggest-attribute=