From 287db4aceafcdb9d5d45b992d2d422f30b25f02a Mon Sep 17 00:00:00 2001
From: David Malcolm <dmalcolm@redhat.com>
Date: Fri, 27 Sep 2019 09:23:16 -0400
Subject: [PATCH 30/60] FIXME: analyzer: documentation

---
 gcc/doc/invoke.texi | 180 +++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 178 insertions(+), 2 deletions(-)

diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
index 7f9a027..bfd7233 100644
--- a/gcc/doc/invoke.texi
+++ b/gcc/doc/invoke.texi
@@ -288,13 +288,30 @@ Objective-C and Objective-C++ Dialects}.
 
 @item Warning Options
 @xref{Warning Options,,Options to Request or Suppress Warnings}.
-@gccoptlist{-fsyntax-only  -fmax-errors=@var{n}  -Wpedantic @gol
+@gccoptlist{--analyzer -fsyntax-only  -fmax-errors=@var{n}  -Wpedantic @gol
 -pedantic-errors @gol
 -w  -Wextra  -Wall  -Waddress  -Waddress-of-packed-member @gol
 -Waggregate-return  -Waligned-new @gol
 -Walloc-zero  -Walloc-size-larger-than=@var{byte-size} @gol
 -Walloca  -Walloca-larger-than=@var{byte-size} @gol
--Wno-aggressive-loop-optimizations  -Warray-bounds  -Warray-bounds=@var{n} @gol
+-Wno-aggressive-loop-optimizations @gol
+-Wno-analyzer-double-fclose @gol
+-Wno-analyzer-double-free @gol
+-Wno-analyzer-dereference-of-uninitialized-pointer @gol
+-Wno-analyzer-dereference-of-freed-pointer @gol
+-Wno-analyzer-dereference-of-pointer-in-stale-stack-frame @gol
+-Wno-analyzer-exposure-through-output-file @gol
+-Wno-analyzer-file-leak @gol
+-Wno-analyzer-free-of-non-heap @gol
+-Wno-analyzer-malloc-leak @gol
+-Wno-analyzer-possible-null-argument @gol
+-Wno-analyzer-possible-null-dereference @gol
+-Wno-analyzer-null-argument @gol
+-Wno-analyzer-null-dereference @gol
+-Wno-analyzer-tainted-array-index @gol
+-Wanalyzer-too-complex @gol
+-Wno-analyzer-use-after-free @gol
+-Warray-bounds  -Warray-bounds=@var{n} @gol
 -Wno-attributes  -Wattribute-alias=@var{n}  @gol
 -Wbool-compare  -Wbool-operation @gol
 -Wno-builtin-declaration-mismatch @gol
@@ -4388,6 +4405,42 @@ The following language-independent options do not enable specific
 warnings but control the kinds of diagnostics produced by GCC@.
 
 @table @gcctabopt
+
+@item --analyzer
+@opindex analyzer
+This option enables an expensive static analysis of program flow
+which looks for ``interesting'' interprocedural paths through the
+code, and issues warnings for problems found on them.
+
+Enabling this option effectively enables the following warnings:
+
+@gccoptlist{ @gol
+-Wanalyzer-double-fclose @gol
+-Wanalyzer-double-free @gol
+-Wanalyzer-dereference-of-uninitialized-pointer @gol
+-Wanalyzer-dereference-of-freed-pointer @gol
+-Wanalyzer-dereference-of-pointer-in-stale-stack-frame @gol
+-Wanalyzer-exposure-through-output-file @gol
+-Wanalyzer-file-leak @gol
+-Wanalyzer-free-of-non-heap @gol
+-Wanalyzer-malloc-leak @gol
+-Wanalyzer-possible-null-argument @gol
+-Wanalyzer-possible-null-dereference @gol
+-Wanalyzer-null-argument @gol
+-Wanalyzer-null-dereference @gol
+-Wanalyzer-tainted-array-index @gol
+-Wanalyzer-use-after-free @gol
+}
+
+
+
+
++Wanalyzer-too-complex
++Common Var(warn_analyzer_too_complex) Init(0) Warning
++Warn if the code is too complicated for the analyzer to fully explore.
++
+
+
 @cindex syntax checking
 @item -fsyntax-only
 @opindex fsyntax-only
@@ -6275,6 +6328,129 @@ See also @option{-Wvla-larger-than=}@samp{byte-size}.
 Disable @option{-Walloca-larger-than=} warnings.  The option is
 equivalent to @option{-Walloca-larger-than=}@samp{SIZE_MAX} or larger.
 
+@item -Wno-analyzer-double-fclose
+@opindex Wanalyzer-double-fclose
+@opindex Wno-analyzer-double-fclose
+This warning requires @option{--analyzer}, which enables it; use
+@option{-Wno-analyzer-double-fclose} to disable it.
+
+This diagnostic warns for paths through the code in which a @code{FILE *}
+can have @code{fclose} called on it more than once.
+
+@item -Wno-analyzer-double-free
+@opindex Wanalyzer-double-free
+@opindex Wno-analyzer-double-free
+This warning requires @option{--analyzer}, which enables it; use
+@option{-Wno-analyzer-double-free} to disable it.
+
+This diagnostic warns for paths through the code in which a pointer
+can have @code{free} called on it more than once.
+
+@item -Wno-analyzer-dereference-of-uninitialized-pointer
+@opindex Wanalyzer-dereference-of-uninitialized-pointer
+@opindex Wno-analyzer-dereference-of-uninitialized-pointer
+This warning requires @option{--analyzer}, which enables it; use
+@option{-Wno-analyzer-dereference-of-uninitialized-pointer} to disable it.
+
+This diagnostic warns for paths through the code in which an uninitialized
+pointer value can be dereferenced.
+
+@item -Wno-analyzer-dereference-of-freed-pointer
+@opindex Wanalyzer-dereference-of-freed-pointer
+@opindex Wno-analyzer-dereference-of-freed-pointer
+This warning requires @option{--analyzer}, which enables it; use
+@option{-Wno-analyzer-dereference-of-freed-pointer} to disable it.
+
+This diagnostic warns for paths through the code in which a pointer
+is dereferenced after a call to @code{free}.
+
+@item -Wno-analyzer-dereference-of-pointer-in-stale-stack-frame
+@opindex Wanalyzer-dereference-of-pointer-in-stale-stack-frame
+@opindex Wno-analyzer-dereference-of-pointer-in-stale-stack-frame
+This warning requires @option{--analyzer}, which enables it; use
+@option{-Wno-analyzer-dereference-of-pointer-in-stale-stack-frame}
+to disable it.
+
+This diagnostic warns for paths through the code in which a pointer
+is dereferenced that points to a variable in a stale stack frame.
+
+@item -Wno-analyzer-exposure-through-output-file
+@opindex Wanalyzer-exposure-through-output-file
+@opindex Wno-analyzer-exposure-through-output-file
+This warning requires @option{--analyzer}, which enables it; use
+@option{-Wno-analyzer-exposure-through-output-file}
+to disable it.
+
+This diagnostic warns for paths through the code in which a
+security-sensitive value is written to an output file
+(such as writing a password to a log file).
+
+@item -Wno-analyzer-file-leak
+@opindex Wanalyzer-file-leak
+@opindex Wno-analyzer-file-leak
+This warning requires @option{--analyzer}, which enables it; use
+@option{-Wno-analyzer-file-leak}
+to disable it.
+
+This diagnostic warns for paths through the code in which a
+@code{<stdio.h>} @code{FILE *} stream object is leaked.
+
+@item -Wno-analyzer-free-of-non-heap
+@opindex Wanalyzer-free-of-non-heap
+@opindex Wno-analyzer-free-of-non-heap
+This warning requires @option{--analyzer}, which enables it; use
+@option{-Wno-analyzer-free-of-non-heap}
+to disable it.
+
+This diagnostic warns for paths through the code in which @code{free}
+is called on a non-heap pointer (e.g. an on-stack buffer, or a global).
+
+@item -Wno-analyzer-malloc-leak
+@opindex Wanalyzer-malloc-leak
+@opindex Wno-analyzer-malloc-leak
+This warning requires @option{--analyzer}, which enables it; use
+@option{-Wno-analyzer-malloc-leak}
+to disable it.
+
+This diagnostic warns for paths through the code in which a
+pointer allocated via @code{malloc} is leaked.
+
+@item -Wno-analyzer-possible-null-argument
+@opindex Wanalyzer-possible-null-argument
+@opindex Wno-analyzer-possible-null-argument
+FIXME
+
+@item -Wno-analyzer-possible-null-dereference
+@opindex Wanalyzer-possible-null-dereference
+@opindex Wno-analyzer-possible-null-dereference
+FIXME
+
+@item -Wno-analyzer-null-argument
+@opindex Wanalyzer-null-argument
+@opindex Wno-analyzer-null-argument
+FIXME
+
+@item -Wno-analyzer-null-dereference
+@opindex Wanalyzer-null-dereference
+@opindex Wno-analyzer-null-dereference
+FIXME
+
+@item -Wno-analyzer-tainted-array-index
+@opindex Wanalyzer-tainted-array-index
+@opindex Wno-analyzer-tainted-array-index
+FIXME
+
+@item -Wanalyzer-too-complex
+@opindex Wno-analyzer-too-complex
+FIXME
+The analyzer uses various heuristics to attempt to explore the control
+flow and data flow in the program, but it is FIXME.
+
+@item -Wno-analyzer-use-after-free
+@opindex Wanalyzer-use-after-free
+@opindex Wno-analyzer-use-after-free
+FIXME
+
 @item -Warray-bounds
 @itemx -Warray-bounds=@var{n}
 @opindex Wno-array-bounds
-- 
1.8.5.3

