From patchwork Wed Jan 17 23:01:02 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Sandra Loosemore X-Patchwork-Id: 84306 Return-Path: X-Original-To: patchwork@sourceware.org Delivered-To: patchwork@sourceware.org Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id D4B113858C42 for ; Wed, 17 Jan 2024 23:01:50 +0000 (GMT) X-Original-To: gcc-patches@gcc.gnu.org Delivered-To: gcc-patches@gcc.gnu.org Received: from esa1.mentor.iphmx.com (esa1.mentor.iphmx.com [68.232.129.153]) by sourceware.org (Postfix) with ESMTPS id 167843858D33 for ; Wed, 17 Jan 2024 23:01:18 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 167843858D33 Authentication-Results: sourceware.org; dmarc=none (p=none dis=none) header.from=codesourcery.com Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=mentor.com ARC-Filter: OpenARC Filter v1.0.0 sourceware.org 167843858D33 Authentication-Results: server2.sourceware.org; arc=none smtp.remote-ip=68.232.129.153 ARC-Seal: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1705532480; cv=none; b=QB/ZjjV4aR0O7k0bGvindvTYxy9bmAsFpdQ62ExDNE6w2fqkb185AbF6BTAvbWQgpR7CV3S2y4gP+k+wc5J5zyOpUKi2J5WXNLvY1aopfi41y127v2kIuN+lSEyIKo36rx1Vr4mbVm1YCi+FNy+NKcwNnEQi4GFZzKJFfdf/G/A= ARC-Message-Signature: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1705532480; c=relaxed/simple; bh=S2hNkYygPTdCgRBgjjiEpo2A6AQCS3+CsR7VOYU504M=; h=From:To:Subject:Date:Message-ID:MIME-Version; b=gwM9J1gZkKDZKTVyQqTMJmYBzFjraD6CgQKI2+H+uqhHwvkejjW5vXz32Qpok1gBeEs84jubhnOdjnapEXzFEBmVMWarqZkzZOBSKfOiin19FmQyOPWuYEQQUmDEqOe/CBvxRbxleTJgMlIeM8u+m6Zk0TglI694mEiKCFvhNjI= ARC-Authentication-Results: i=1; server2.sourceware.org X-CSE-ConnectionGUID: PlFXC+goTtey8182qqBDbg== X-CSE-MsgGUID: 3+snumR1Sv+3Oy20XwtT0A== X-IronPort-AV: E=Sophos;i="6.05,201,1701158400"; d="scan'208";a="31875112" Received: from orw-gwy-01-in.mentorg.com ([192.94.38.165]) by esa1.mentor.iphmx.com with ESMTP; 17 Jan 2024 15:01:17 -0800 IronPort-SDR: NuZjfmWhhRuFh7SSJRRERkOls1GVCW52gzgjAsn/J+2oDlPBWkPBFC9i5hsDrWeqjKeDB54glX fxwe7rgoQ8ahKmz7Cm08J7J3XHD5wmnPyIOZk9kZVIfy2v+YhxhB2SlfHBXXt1dI1e6IRxCDOs TiNteZNxFK1bH/q2zt9F4hCFtAIKfMnkprY73uqpxn3Gllx102jvBiGjMxkEttOvmFlCgHu4YC naDp+Tm2Vvm4jY32a7n5GwaLMQmPo1SwILKfKeNn1niCLV3aqV8CEq/k+ssyKfXAYHoFcm8+OF /Q0= From: Sandra Loosemore To: Subject: [COMMITTED] Clean up documentation for -Wstrict-flex-arrays [PR111659] Date: Wed, 17 Jan 2024 16:01:02 -0700 Message-ID: <20240117230102.1413330-1-sandra@codesourcery.com> X-Mailer: git-send-email 2.34.1 MIME-Version: 1.0 X-ClientProxiedBy: svr-orw-mbx-11.mgc.mentorg.com (147.34.90.211) To svr-orw-mbx-13.mgc.mentorg.com (147.34.90.213) X-Spam-Status: No, score=-10.1 required=5.0 tests=BAYES_00, GIT_PATCH_0, HEADER_FROM_DIFFERENT_DOMAINS, KAM_DMARC_STATUS, SPF_HELO_PASS, SPF_PASS, TXREP, T_SCC_BODY_TEXT_LINE autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org X-BeenThere: gcc-patches@gcc.gnu.org X-Mailman-Version: 2.1.30 Precedence: list List-Id: Gcc-patches mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: gcc-patches-bounces+patchwork=sourceware.org@gcc.gnu.org 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. --- gcc/doc/extend.texi | 30 +++++++++++++++----------- gcc/doc/invoke.texi | 51 ++++++++++++++++++++++++++------------------- 2 files changed, 47 insertions(+), 34 deletions(-) diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi index 89e823629e3..91f0b669b9e 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 43fd3c3a3cd..a537be66736 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=