From patchwork Fri Mar 17 04:01:57 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Sandra Loosemore X-Patchwork-Id: 66493 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 54A253851145 for ; Fri, 17 Mar 2023 04:02:25 +0000 (GMT) X-Original-To: gcc-patches@gcc.gnu.org Delivered-To: gcc-patches@gcc.gnu.org Received: from esa2.mentor.iphmx.com (esa2.mentor.iphmx.com [68.232.141.98]) by sourceware.org (Postfix) with ESMTPS id E8B463858423 for ; Fri, 17 Mar 2023 04:02:02 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org E8B463858423 Authentication-Results: sourceware.org; dmarc=none (p=none dis=none) header.from=codesourcery.com Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=mentor.com X-IronPort-AV: E=Sophos;i="5.98,267,1673942400"; d="scan'208";a="101935272" Received: from orw-gwy-01-in.mentorg.com ([192.94.38.165]) by esa2.mentor.iphmx.com with ESMTP; 16 Mar 2023 20:02:01 -0800 IronPort-SDR: U4VbPLWH3RiShAeqDYD0da0y1IdttBwknBrgMsvKpnWli31hf3JlOhidOXzyrTbhD3iG1Fhf6q W6HQuUlexsHBfOR/PPa/eSGT+zvVSIkb3BZleP90kFvW44NYtEE5WduV8awerly4/WSFb1NhL7 ngzZNBnY4kTC7WAKtPtxZcdKAAsO1jRy31iGJBEiXPt8IqD2BpJV7Pvbu+ujY4xE71xAP5w2Mr WFEik4dgQrxEWxlCgBT+aiN2Ua2l8ujB0jgRntGHvnUisbEosgaBHtO0yK1YCiO/xaLN8aGX89 jJw= Message-ID: <527dd94b-9193-0887-4830-0ba0b3a83792@codesourcery.com> Date: Thu, 16 Mar 2023 22:01:57 -0600 MIME-Version: 1.0 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101 Thunderbird/102.7.1 Content-Language: en-US To: "gcc-patches@gcc.gnu.org" From: Sandra Loosemore Subject: [committed] Docs: Fix some too-long lines 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=-9.8 required=5.0 tests=BAYES_00, GIT_PATCH_0, HEADER_FROM_DIFFERENT_DOMAINS, KAM_DMARC_STATUS, RCVD_IN_MSPIKE_H2, SPF_HELO_PASS, SPF_PASS, TXREP 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.29 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 Sender: "Gcc-patches" I noticed when looking at other things last week that there were a whole bunch of too-long lines overflowing into the right margin in the PDF version of the GCC manual. This patch fixes some of them. There are still a whole bunch of especially bad ones in the diagnostic message formatting examples that I haven't found a satisfactory way to fix yet :-( but at least this patch is an incremental improvement. -Sandra commit 35a80d19b69df59f52800f34bac1df3cb0293735 Author: Sandra Loosemore Date: Thu Mar 16 21:05:53 2023 +0000 Docs: Fix some too-long lines in Texinfo manual. gcc/ChangeLog: * doc/extend.texi (Common Function Attributes) : Fix bad line breaks in examples. : Fix bad line breaks in running text, also copy-edit for consistency. (Extended Asm) : Fix @multitable width. * doc/invoke.texi (Option Summary) : Fix misplaced @gol. (C++ Dialect Options) <-fcontracts>: Add line break in example. <-Wctad-maybe-unsupported>: Likewise. <-Winvalid-constexpr>: Likewise. (Warning Options) <-Wdangling-pointer>: Likewise. <-Winterference-size>: Likewise. <-Wvla-parameter>: Likewise. (Static Analyzer Options): Fix bad line breaks in running text, plus add some missing markup. (Optimize Options) : Fix more bad line breaks in running text. diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi index fd3745c5608..39d45df8d89 100644 --- a/gcc/doc/extend.texi +++ b/gcc/doc/extend.texi @@ -2611,8 +2611,11 @@ the @code{puts} function, or the second and third arguments to the @code{memcpy} function. @smallexample -__attribute__ ((access (read_only, 1))) int puts (const char*); -__attribute__ ((access (read_only, 2, 3))) void* memcpy (void*, const void*, size_t); +__attribute__ ((access (read_only, 1))) +int puts (const char*); + +__attribute__ ((access (read_only, 2, 3))) +void* memcpy (void*, const void*, size_t); @end smallexample The @code{read_write} access mode applies to arguments of pointer types @@ -2624,7 +2627,8 @@ of the use of the @code{read_write} access mode is the first argument to the @code{strcat} function. @smallexample -__attribute__ ((access (read_write, 1), access (read_only, 2))) char* strcat (char*, const char*); +__attribute__ ((access (read_write, 1), access (read_only, 2))) +char* strcat (char*, const char*); @end smallexample The @code{write_only} access mode applies to arguments of pointer types @@ -2636,8 +2640,11 @@ the @code{strcpy} function, or the first two arguments to the @code{fgets} function. @smallexample -__attribute__ ((access (write_only, 1), access (read_only, 2))) char* strcpy (char*, const char*); -__attribute__ ((access (write_only, 1, 2), access (read_write, 3))) int fgets (char*, int, FILE*); +__attribute__ ((access (write_only, 1), access (read_only, 2))) +char* strcpy (char*, const char*); + +__attribute__ ((access (write_only, 1, 2), access (read_write, 3))) +int fgets (char*, int, FILE*); @end smallexample The access mode @code{none} specifies that the pointer to which it applies @@ -3444,22 +3451,23 @@ deallocation pairs marked with the @code{malloc}. In particular: @itemize @bullet @item -The analyzer will emit a @option{-Wanalyzer-mismatching-deallocation} +The analyzer emits a @option{-Wanalyzer-mismatching-deallocation} diagnostic if there is an execution path in which the result of an allocation call is passed to a different deallocator. @item -The analyzer will emit a @option{-Wanalyzer-double-free} +The analyzer emits a @option{-Wanalyzer-double-free} diagnostic if there is an execution path in which a value is passed more than once to a deallocation call. @item -The analyzer will consider the possibility that an allocation function -could fail and return NULL. It will emit -@option{-Wanalyzer-possible-null-dereference} and -@option{-Wanalyzer-possible-null-argument} diagnostics if there are +The analyzer considers the possibility that an allocation function +could fail and return null. If there are execution paths in which an unchecked result of an allocation call is -dereferenced or passed to a function requiring a non-null argument. +dereferenced or passed to a function requiring a non-null argument, +it emits +@option{-Wanalyzer-possible-null-dereference} and +@option{-Wanalyzer-possible-null-argument} diagnostics. If the allocator always returns non-null, use @code{__attribute__ ((returns_nonnull))} to suppress these warnings. For example: @@ -3469,26 +3477,26 @@ char *xstrdup (const char *) @end smallexample @item -The analyzer will emit a @option{-Wanalyzer-use-after-free} +The analyzer emits a @option{-Wanalyzer-use-after-free} diagnostic if there is an execution path in which the memory passed by pointer to a deallocation call is used after the deallocation. @item -The analyzer will emit a @option{-Wanalyzer-malloc-leak} diagnostic if +The analyzer emits a @option{-Wanalyzer-malloc-leak} diagnostic if there is an execution path in which the result of an allocation call is leaked (without being passed to the deallocation function). @item -The analyzer will emit a @option{-Wanalyzer-free-of-non-heap} diagnostic +The analyzer emits a @option{-Wanalyzer-free-of-non-heap} diagnostic if a deallocation function is used on a global or on-stack variable. @end itemize -The analyzer assumes that deallocators can gracefully handle the @code{NULL} +The analyzer assumes that deallocators can gracefully handle the null pointer. If this is not the case, the deallocator can be marked with @code{__attribute__((nonnull))} so that @option{-fanalyzer} can emit a @option{-Wanalyzer-possible-null-argument} diagnostic for code paths -in which the deallocator is called with NULL. +in which the deallocator is called with null. @cindex @code{no_icf} function attribute @item no_icf @@ -11039,7 +11047,7 @@ lab: @noindent The following table shows the modifiers supported by all targets and their effects: -@multitable {Modifier} {Description} {Example} +@multitable @columnfractions 0.15 0.7 0.15 @headitem Modifier @tab Description @tab Example @item @code{c} @tab Require a constant operand and print the constant expression with no punctuation. diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi index 8adcddb7a19..10c9fd83571 100644 --- a/gcc/doc/invoke.texi +++ b/gcc/doc/invoke.texi @@ -715,8 +715,8 @@ Objective-C and Objective-C++ Dialects}. @xref{Developer Options,,GCC Developer Options}. @gccoptlist{-d@var{letters} -dumpspecs -dumpmachine -dumpversion @gol -dumpfullversion -fcallgraph-info@r{[}=su,da@r{]} --fchecking -fchecking=@var{n} --fdbg-cnt-list @gol -fdbg-cnt=@var{counter-value-list} @gol +-fchecking -fchecking=@var{n} @gol +-fdbg-cnt-list -fdbg-cnt=@var{counter-value-list} @gol -fdisable-ipa-@var{pass_name} @gol -fdisable-rtl-@var{pass_name} @gol -fdisable-rtl-@var{pass-name}=@var{range-list} @gol @@ -3168,7 +3168,8 @@ into shape for a future C++ standard. On violation of a checked contract, the violation handler is called. Users can replace the violation handler by defining @smallexample -void handle_contract_violation (const std::experimental::contract_violation&); +void +handle_contract_violation (const std::experimental::contract_violation&); @end smallexample There are different sets of additional flags that can be used together @@ -3711,7 +3712,8 @@ struct allow_ctad_t; // any name works template struct S @{ S(T) @{ @} @}; -S(allow_ctad_t) -> S; // guide with incomplete parameter type will never be considered +// Guide with incomplete parameter type will never be considered. +S(allow_ctad_t) -> S; @end smallexample @opindex Wctor-dtor-privacy @@ -3903,7 +3905,8 @@ void f (int& i); constexpr void g (int& i) @{ - f(i); // warns by default in C++20, in C++23 only with -Winvalid-constexpr + // Warns by default in C++20, in C++23 only with -Winvalid-constexpr. + f(i); @} @end smallexample @@ -9062,7 +9065,8 @@ For example int f (int c1, int c2, x) @{ char *p = strchr ((char[])@{ c1, c2 @}, c3); - return p ? *p : 'x'; // warning: dangling pointer to a compound literal + // warning: dangling pointer to a compound literal + return p ? *p : 'x'; @} @end smallexample In the following function the store of the address of the local variable @@ -9071,7 +9075,8 @@ In the following function the store of the address of the local variable void g (int **p) @{ int x = 7; - *p = &x; // warning: storing the address of a local variable in *p + // warning: storing the address of a local variable in *p + *p = &x; @} @end smallexample @@ -9091,7 +9096,8 @@ void f (char *s) char a[12] = "tmpname"; s = a; @} - strcat (s, ".tmp"); // warning: dangling pointer to a may be used + // warning: dangling pointer to a may be used + strcat (s, ".tmp"); ... @} @end smallexample @@ -9840,8 +9846,10 @@ avoid false sharing in concurrent code: @smallexample struct independent_fields @{ - alignas(std::hardware_destructive_interference_size) std::atomic one; - alignas(std::hardware_destructive_interference_size) std::atomic two; + alignas(std::hardware_destructive_interference_size) + std::atomic one; + alignas(std::hardware_destructive_interference_size) + std::atomic two; @}; @end smallexample @@ -9994,14 +10002,16 @@ parameter in excess of the actual VLA bound triggers a warning as well. @smallexample void f (int n, int[n]); -void f (int, int[]); // warning: argument 2 previously declared as a VLA +// warning: argument 2 previously declared as a VLA +void f (int, int[]); void g (int n) @{ if (n > 4) return; int a[n]; - f (sizeof a, a); // warning: access to a by f may be out of bounds + // warning: access to a by f may be out of bounds + f (sizeof a, a); @dots{} @} @@ -10190,9 +10200,8 @@ limit. The @option{-Wanalyzer-too-complex} option warns if this occurs. @opindex Wanalyzer-allocation-size @opindex Wno-analyzer-allocation-size @item -Wno-analyzer-allocation-size -This warning requires @option{-fanalyzer}, which enables it; use -@option{-Wno-analyzer-allocation-size} -to disable it. +This warning requires @option{-fanalyzer}, which enables it; +to disable it, use @option{-Wno-analyzer-allocation-size}. This diagnostic warns for paths through the code in which a pointer to a buffer is assigned to point at a buffer with a size that is not a @@ -10473,10 +10482,10 @@ See @uref{https://cwe.mitre.org/data/definitions/762.html, CWE-762: Mismatched M @opindex Wanalyzer-out-of-bounds @opindex Wno-analyzer-out-of-bounds @item -Wno-analyzer-out-of-bounds -This warning requires @option{-fanalyzer} to enable it; use +This warning requires @option{-fanalyzer}, which enables it; use @option{-Wno-analyzer-out-of-bounds} to disable it. -This diagnostic warns for path through the code in which a buffer is +This diagnostic warns for paths through the code in which a buffer is definitely read or written out-of-bounds. The diagnostic applies for cases where the analyzer is able to determine a constant offset and for accesses past the end of a buffer, also a constant capacity. Further, @@ -10870,6 +10879,7 @@ memory-management functions: @item @code{strndup} @end itemize +@noindent of the following functions for working with file descriptors: @itemize @bullet @@ -10884,6 +10894,7 @@ of the following functions for working with file descriptors: @item @code{socket}, @code{bind}, @code{listen}, @code{accept}, and @code{connect} @end itemize +@noindent of the following functions for working with @code{} streams: @itemize @bullet @item The built-in functions @code{__builtin_fprintf}, @@ -10910,6 +10921,7 @@ of the following functions for working with @code{} streams: @item @code{fwrite} @end itemize +@noindent and of the following functions: @itemize @bullet @@ -10934,10 +10946,12 @@ In addition, various functions with an @code{__analyzer_} prefix have special meaning to the analyzer, described in the GCC Internals manual. Pertinent parameters for controlling the exploration are: -@option{--param analyzer-bb-explosion-factor=@var{value}}, -@option{--param analyzer-max-enodes-per-program-point=@var{value}}, -@option{--param analyzer-max-recursion-depth=@var{value}}, and -@option{--param analyzer-min-snodes-for-call-summary=@var{value}}. +@itemize @bullet +@item @option{--param analyzer-bb-explosion-factor=@var{value}} +@item @option{--param analyzer-max-enodes-per-program-point=@var{value}} +@item @option{--param analyzer-max-recursion-depth=@var{value}} +@item @option{--param analyzer-min-snodes-for-call-summary=@var{value}} +@end itemize The following options control the analyzer. @@ -11140,7 +11154,7 @@ other events intended for debugging the analyzer. @item -fdump-analyzer Dump internal details about what the analyzer is doing to @file{@var{file}.analyzer.txt}. -This option is overridden by @option{-fdump-analyzer-stderr}. +@option{-fdump-analyzer-stderr} overrides this option. @opindex fdump-analyzer-stderr @item -fdump-analyzer-stderr @@ -12953,7 +12967,8 @@ callers are impacted, therefore need to be patched as well. @option{-flive-patching=inline-clone} disables the following optimization flags: @gccoptlist{-fwhole-program -fipa-pta -fipa-reference -fipa-ra @gol -fipa-icf -fipa-icf-functions -fipa-icf-variables @gol --fipa-bit-cp -fipa-vrp -fipa-pure-const -fipa-reference-addressable @gol +-fipa-bit-cp -fipa-vrp -fipa-pure-const @gol +-fipa-reference-addressable @gol -fipa-stack-alignment -fipa-modref} @item inline-only-static @@ -16172,9 +16187,8 @@ constructs are handled by the @samp{parloops} pass, en bloc. This is the current default. @item openacc-privatization -Specify mode of OpenACC privatization diagnostics for -@option{-fopt-info-omp-note} and applicable -@option{-fdump-tree-*-details}. +Control whether the @option{-fopt-info-omp-note} and applicable +@option{-fdump-tree-*-details} options emit OpenACC privatization diagnostics. With @option{--param=openacc-privatization=quiet}, don't diagnose. This is the current default. With @option{--param=openacc-privatization=noisy}, do diagnose.