From 4ace81b61183b055a7951e8599512ef04a51768e Mon Sep 17 00:00:00 2001 From: Sandra Loosemore Date: Thu, 16 Mar 2023 21:05:53 +0000 Subject: [PATCH] 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. --- gcc/doc/extend.texi | 44 ++++++++++++++++++++--------------- gcc/doc/invoke.texi | 66 ++++++++++++++++++++++++++++++++--------------------- 2 files changed, 66 insertions(+), 44 deletions(-) diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi index fd3745c..39d45df 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 8adcddb..10c9fd8 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. -- 2.7.4