From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: by sourceware.org (Postfix, from userid 1851) id 98B2C38357B0; Mon, 14 Nov 2022 03:07:39 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 98B2C38357B0 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gcc.gnu.org; s=default; t=1668395259; bh=hdOEurvhzyemXXodd6bAPLrhMH8F1LNejtKAeQabffQ=; h=From:To:Subject:Date:From; b=hu7QD/i5nhUYN3ha2LzsysPTdgnxPwDQbNqBGz+/l2lYRX9voyvZTRnEClLvGti5O 4EUE2tR0HP7IQu+v1jUpZ9bsIqvFSj+PnM6jkGGkTW3xqC91YR6rhXqu42mnmFgxwu ftx5LhqhUDDlfr54kuPTcAhYCtMVpkHNVIffcykA= Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit From: Martin Liska To: gcc-cvs@gcc.gnu.org Subject: [gcc(refs/users/marxin/heads/revert-sphinx-v2)] doc: port new documentation from Sphinx X-Act-Checkin: gcc X-Git-Author: Martin Liska X-Git-Refname: refs/users/marxin/heads/revert-sphinx-v2 X-Git-Oldrev: f5f4a595b9d0752b45444bc1fb12b74007e24fb5 X-Git-Newrev: 1c4a42916dcb49885f9d2c5a5ca44859c9dfe605 Message-Id: <20221114030739.98B2C38357B0@sourceware.org> Date: Mon, 14 Nov 2022 03:07:39 +0000 (GMT) List-Id: https://gcc.gnu.org/g:1c4a42916dcb49885f9d2c5a5ca44859c9dfe605 commit 1c4a42916dcb49885f9d2c5a5ca44859c9dfe605 Author: Martin Liska Date: Mon Nov 14 03:20:25 2022 +0100 doc: port new documentation from Sphinx gcc/ChangeLog: * doc/contrib.texi: Port from Sphinx. * doc/cpp.texi: Likewise. * doc/install.texi: Likewise. * doc/invoke.texi: Likewise. gcc/fortran/ChangeLog: * gfortran.texi: Port from Sphinx. Diff: --- gcc/doc/contrib.texi | 2 +- gcc/doc/cpp.texi | 3 ++ gcc/doc/install.texi | 4 +- gcc/doc/invoke.texi | 135 +++++++++++++++++++++++++++++++++++++++++++++- gcc/fortran/gfortran.texi | 3 +- 5 files changed, 139 insertions(+), 8 deletions(-) diff --git a/gcc/doc/contrib.texi b/gcc/doc/contrib.texi index e14cf5e4751..e3de5cc9c5d 100644 --- a/gcc/doc/contrib.texi +++ b/gcc/doc/contrib.texi @@ -9,7 +9,7 @@ The GCC project would like to thank its many contributors. Without them the project would not have been nearly as successful as it has been. Any omissions in this list are accidental. Feel free to contact -@email{law@@redhat.com} or @email{gerald@@pfeifer.com} if you have been left +@email{jlaw@@ventanamicro.com} or @email{gerald@@pfeifer.com} if you have been left out or some of your contributions are not listed. Please keep this list in alphabetical order. diff --git a/gcc/doc/cpp.texi b/gcc/doc/cpp.texi index 90b2767e39a..1be29eb605e 100644 --- a/gcc/doc/cpp.texi +++ b/gcc/doc/cpp.texi @@ -3843,6 +3843,9 @@ file will never be read again, no matter what. It is a less-portable alternative to using @samp{#ifndef} to guard the contents of header files against multiple inclusions. +@code{#pragma region @{tokens@}...}, @code{#pragma endregion @{tokens@}...} +These pragmas are accepted, but have no effect. + @end ftable @node Other Directives diff --git a/gcc/doc/install.texi b/gcc/doc/install.texi index a01b8053afe..589c64965b2 100644 --- a/gcc/doc/install.texi +++ b/gcc/doc/install.texi @@ -3102,9 +3102,7 @@ but it can give you confidence in your new GCC installation or point out problems before you install and start using your new GCC@. First, you must have @uref{download.html,,downloaded the testsuites}. -These are part of the full distribution, but if you downloaded the -``core'' compiler plus any front ends, you must download the testsuites -separately. +These are included in the source tarball. Second, you must have the testing tools installed. This includes @uref{https://www.gnu.org/software/dejagnu/,,DejaGnu}, Tcl, and Expect; diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi index 975ee64103f..bd1d9f2b270 100644 --- a/gcc/doc/invoke.texi +++ b/gcc/doc/invoke.texi @@ -458,6 +458,7 @@ Objective-C and Objective-C++ Dialects}. -Wno-analyzer-file-leak @gol -Wno-analyzer-free-of-non-heap @gol -Wno-analyzer-imprecise-fp-arithmetic @gol +-Wno-analyzer-infinite-recursion @gol -Wno-analyzer-jump-through-null @gol -Wno-analyzer-malloc-leak @gol -Wno-analyzer-mismatching-deallocation @gol @@ -471,6 +472,7 @@ Objective-C and Objective-C++ Dialects}. -Wno-analyzer-shift-count-overflow @gol -Wno-analyzer-stale-setjmp-buffer @gol -Wno-analyzer-tainted-allocation-size @gol +-Wno-analyzer-tainted-assertion @gol -Wno-analyzer-tainted-array-index @gol -Wno-analyzer-tainted-divisor @gol -Wno-analyzer-tainted-offset @gol @@ -3667,6 +3669,16 @@ const T& foo (const T&) @{ @dots{} @} #pragma GCC diagnostic pop @end smallexample +@option{-Wdangling-reference} also warns about code like + +@smallexample +auto p = std::minmax(1, 2); +@end smallexample + +where @code{std::minmax} returns @code{std::pair}, and +both references dangle after the end of the full expression that contains +the call to @code{std::minmax}. + This warning is enabled by @option{-Wall}. @item -Wdelete-non-virtual-dtor @r{(C++ and Objective-C++ only)} @@ -6482,6 +6494,10 @@ optimization levels but requires optimization in order to detect infinite recursion in calls between two or more functions. @option{-Winfinite-recursion} is included in @option{-Wall}. +Compare with @option{-Wanalyzer-infinite-recursion} which provides a +similar diagnostic, but is implemented in a different way (as part of +@option{-fanalyzer}). + @item -Winit-self @r{(C, C++, Objective-C and Objective-C++ only)} @opindex Winit-self @opindex Wno-init-self @@ -9892,6 +9908,7 @@ Enabling this option effectively enables the following warnings: @gccoptlist{ @gol -Wanalyzer-allocation-size @gol +-Wanalyzer-deref-before-check @gol -Wanalyzer-double-fclose @gol -Wanalyzer-double-free @gol -Wanalyzer-exposure-through-output-file @gol @@ -9904,6 +9921,7 @@ Enabling this option effectively enables the following warnings: -Wanalyzer-file-leak @gol -Wanalyzer-free-of-non-heap @gol -Wanalyzer-imprecise-fp-arithmetic @gol +-Wanalyzer-infinite-recursion @gol -Wanalyzer-jump-through-null @gol -Wanalyzer-malloc-leak @gol -Wanalyzer-mismatching-deallocation @gol @@ -9962,6 +9980,30 @@ multiple of @code{sizeof (*pointer)}. See @uref{https://cwe.mitre.org/data/definitions/131.html, CWE-131: Incorrect Calculation of Buffer Size}. +@item -Wno-analyzer-deref-before-check +@opindex Wanalyzer-deref-before-check +@opindex Wno-analyzer-deref-before-check +This warning requires @option{-fanalyzer}, which enables it; use +@option{-Wno-analyzer-deref-before-check} +to disable it. + +This diagnostic warns for paths through the code in which a pointer +is checked for @code{NULL} *after* it has already been +dereferenced, suggesting that the pointer could have been NULL. +Such cases suggest that the check for NULL is either redundant, +or that it needs to be moved to before the pointer is dereferenced. + +This diagnostic also considers values passed to a function argument +marked with @code{__attribute__((nonnull))} as requiring a non-NULL +value, and thus will complain if such values are checked for @code{NULL} +after returning from such a function call. + +This diagnostic is unlikely to be reported when any level of optimization +is enabled, as GCC's optimization logic will typically consider such +checks for NULL as being redundant, and optimize them away before the +analyzer "sees" them. Hence optimization should be disabled when +attempting to trigger this diagnostic. + @item -Wno-analyzer-double-fclose @opindex Wanalyzer-double-fclose @opindex Wno-analyzer-double-fclose @@ -10118,6 +10160,30 @@ arithmetic is used in locations where precise computation is needed. This diagnostic only warns on use of floating-point operands inside the calculation of an allocation size at the moment. +@item -Wno-analyzer-infinite-recursion +@opindex Wanalyzer-infinite-recursion +@opindex Wno-analyzer-infinite-recursion +This warning requires @option{-fanalyzer}, which enables it; use +@option{-Wno-analyzer-infinite-recursion} to disable it. + +This diagnostics warns for paths through the code which appear to +lead to infinite recursion. + +Specifically, when the analyzer "sees" a recursive call, it will compare +the state of memory at the entry to the new frame with that at the entry +to the previous frame of that function on the stack. The warning is +issued if nothing in memory appears to be changing; any changes observed +to parameters or globals are assumed to lead to termination of the +recursion and thus suppress the warning. + +This diagnostic is likely to miss cases of infinite recursion that +are convered to iteration by the optimizer before the analyzer "sees" +them. Hence optimization should be disabled when attempting to trigger +this diagnostic. + +Compare with @option{-Winfinite-recursion}, which provides a similar +diagnostic, but is implemented in a different way. + @item -Wno-analyzer-jump-through-null @opindex Wanalyzer-jump-through-null @opindex Wno-analyzer-jump-through-null @@ -10292,6 +10358,69 @@ of service attack. See @uref{https://cwe.mitre.org/data/definitions/789.html, CWE-789: Memory Allocation with Excessive Size Value}. +@item -Wno-analyzer-tainted-assertion +@opindex Wanalyzer-tainted-assertion +@opindex Wno-analyzer-tainted-assertion + +This warning requires both @option{-fanalyzer} and +@option{-fanalyzer-checker=taint} to enable it; +use @option{-Wno-analyzer-tainted-assertion} to disable it. + +This diagnostic warns for paths through the code in which a value +that could be under an attacker's control is used as part of a +condition without being first sanitized, and that condition guards a +call to a function marked with attribute @code{noreturn} +(such as the function @code{__builtin_unreachable}). Such functions +typically indicate abnormal termination of the program, such as for +assertion failure handlers. For example: + +@smallexample +assert (some_tainted_value < SOME_LIMIT); +@end smallexample + +In such cases: + +@itemize +@item +when assertion-checking is enabled: an attacker could trigger +a denial of service by injecting an assertion failure + +@item +when assertion-checking is disabled, such as by defining @code{NDEBUG}, +an attacker could inject data that subverts the process, since it +presumably violates a precondition that is being assumed by the code. + +@end itemize + +Note that when assertion-checking is disabled, the assertions are +typically removed by the preprocessor before the analyzer has a chance +to "see" them, so this diagnostic can only generate warnings on builds +in which assertion-checking is enabled. + +For the purpose of this warning, any function marked with attribute +@code{noreturn} is considered as a possible assertion failure +handler, including @code{__builtin_unreachable}. Note that these functions +are sometimes removed by the optimizer before the analyzer "sees" them. +Hence optimization should be disabled when attempting to trigger this +diagnostic. + +See @uref{https://cwe.mitre.org/data/definitions/617.html, CWE-617: Reachable Assertion}. + +The warning can also report problematic constructions such as + +@smallexample +switch (some_tainted_value) @{ +case 0: + /* [...etc; various valid cases omitted...] */ + break; + +default: + __builtin_unreachable (); /* BUG: attacker can trigger this */ +@} +@end smallexample + +despite the above not being an assertion failure, strictly speaking. + @item -Wno-analyzer-tainted-array-index @opindex Wanalyzer-tainted-array-index @opindex Wno-analyzer-tainted-array-index @@ -10586,6 +10715,7 @@ to enable them. following warnings from @option{-fanalyzer}: @gccoptlist{ @gol +-Wanalyzer-deref-before-check @gol -Wanalyzer-double-fclose @gol -Wanalyzer-double-free @gol -Wanalyzer-exposure-through-output-file @gol @@ -19862,8 +19992,9 @@ performance of the code. Permissible values for this option are: @samp{cortex-a57.cortex-a53}, @samp{cortex-a72.cortex-a53}, @samp{cortex-a73.cortex-a35}, @samp{cortex-a73.cortex-a53}, @samp{cortex-a75.cortex-a55}, @samp{cortex-a76.cortex-a55}, -@samp{cortex-r82}, @samp{cortex-x1}, @samp{cortex-x2}, -@samp{cortex-a510}, @samp{cortex-a710}, @samp{ampere1}, @samp{native}. +@samp{cortex-r82}, @samp{cortex-x1}, @samp{cortex-x1c}, @samp{cortex-x2}, +@samp{cortex-a510}, @samp{cortex-a710}, @samp{cortex-a715}, @samp{ampere1}, +@samp{native}. The values @samp{cortex-a57.cortex-a53}, @samp{cortex-a72.cortex-a53}, @samp{cortex-a73.cortex-a35}, @samp{cortex-a73.cortex-a53}, diff --git a/gcc/fortran/gfortran.texi b/gcc/fortran/gfortran.texi index 4b4ecd528a7..60fac2e0417 100644 --- a/gcc/fortran/gfortran.texi +++ b/gcc/fortran/gfortran.texi @@ -3763,8 +3763,7 @@ is used for dummy arguments; with @code{VALUE}, those variables are passed by value. For @code{OPTIONAL} dummy arguments, an absent argument is denoted -by a NULL pointer, except for scalar dummy arguments of type -@code{INTEGER}, @code{LOGICAL}, @code{REAL} and @code{COMPLEX} +by a NULL pointer, except for scalar dummy arguments of intrinsic type which have the @code{VALUE} attribute. For those, a hidden Boolean argument (@code{logical(kind=C_bool),value}) is used to indicate whether the argument is present.