[analyzer] Extend the documentation of MallocOverflow

Previously by following the documentation it was not immediately clear
what the capabilities of this checker are.

In this patch, I add some clarification on when does the checker issue a
report and what it's limitations are.
I'm also advertising suppressing such reports by adding an assertion, as
demonstrated by the test3().
I'm highlighting that this checker might produce an extensive amount of
findings, but it might be still useful for code audits.

Reviewed By: martong

Differential Revision: https://reviews.llvm.org/D107756

diff --git a/clang/docs/analyzer/checkers.rst b/clang/docs/analyzer/checkers.rst
index 9a74dff..66c540e 100644 (file)
--- a/clang/docs/analyzer/checkers.rst
+++ b/clang/docs/analyzer/checkers.rst
@@ -2154,7 +2154,14 @@ Warn about buffer overflows (newer checker).
 
 alpha.security.MallocOverflow (C)
 """""""""""""""""""""""""""""""""
-Check for overflows in the arguments to malloc().
+Check for overflows in the arguments to ``malloc()``.
+It tries to catch ``malloc(n * c)`` patterns, where:
+ - ``n``: a variable or member access of an object
+ - ``c``: a constant foldable integral
+
+This checker was designed for code audits, so expect false-positive reports.
+One is supposed to silence this checker by ensuring proper bounds checking on
+the variable in question using e.g. an ``assert()`` or a branch.
 
 .. code-block:: c
 
@@ -2168,6 +2175,26 @@ Check for overflows in the arguments to malloc().
    void *p = malloc(n * sizeof(int)); // no warning
  }
 
+ void test3(int n) {
+   assert(n <= 100 && "Contract violated.");
+   void *p = malloc(n * sizeof(int)); // no warning
+ }
+
+Limitations:
+ - The checker won't warn for variables involved in explicit casts,
+   since that might limit the variable's domain.
+   E.g.: ``(unsigned char)int x`` would limit the domain to ``[0,255]``.
+   The checker will miss the true-positive cases when the explicit cast would
+   not tighten the domain to prevent the overflow in the subsequent
+   multiplication operation.
+
+ - If the variable ``n`` participates in a comparison anywhere in the enclosing
+   function's scope, even after the ``malloc()``, the report will be still
+   suppressed.
+
+ - It is an AST-based checker, thus it does not make use of the
+   path-sensitive taint-analysis.
+
 .. _alpha-security-MmapWriteExec:
 
 alpha.security.MmapWriteExec (C)