Home | History | Annotate | Download | only in analyzer
      1 ============
      2 Debug Checks
      3 ============
      4 
      5 .. contents::
      6    :local:
      7 
      8 The analyzer contains a number of checkers which can aid in debugging. Enable
      9 them by using the "-analyzer-checker=" flag, followed by the name of the
     10 checker.
     11 
     12 
     13 General Analysis Dumpers
     14 ========================
     15 
     16 These checkers are used to dump the results of various infrastructural analyses
     17 to stderr. Some checkers also have "view" variants, which will display a graph
     18 using a 'dot' format viewer (such as Graphviz on OS X) instead.
     19 
     20 - debug.DumpCallGraph, debug.ViewCallGraph: Show the call graph generated for
     21   the current translation unit. This is used to determine the order in which to
     22   analyze functions when inlining is enabled.
     23 
     24 - debug.DumpCFG, debug.ViewCFG: Show the CFG generated for each top-level
     25   function being analyzed.
     26 
     27 - debug.DumpDominators: Shows the dominance tree for the CFG of each top-level
     28   function.
     29 
     30 - debug.DumpLiveVars: Show the results of live variable analysis for each
     31   top-level function being analyzed.
     32 
     33 - debug.ViewExplodedGraph: Show the Exploded Graphs generated for the
     34   analysis of different functions in the input translation unit. When there
     35   are several functions analyzed, display one graph per function. Beware 
     36   that these graphs may grow very large, even for small functions.
     37 
     38 Path Tracking
     39 =============
     40 
     41 These checkers print information about the path taken by the analyzer engine.
     42 
     43 - debug.DumpCalls: Prints out every function or method call encountered during a
     44   path traversal. This is indented to show the call stack, but does NOT do any
     45   special handling of branches, meaning different paths could end up
     46   interleaved.
     47 
     48 - debug.DumpTraversal: Prints the name of each branch statement encountered
     49   during a path traversal ("IfStmt", "WhileStmt", etc). Currently used to check
     50   whether the analysis engine is doing BFS or DFS.
     51 
     52 
     53 State Checking
     54 ==============
     55 
     56 These checkers will print out information about the analyzer state in the form
     57 of analysis warnings. They are intended for use with the -verify functionality
     58 in regression tests.
     59 
     60 - debug.TaintTest: Prints out the word "tainted" for every expression that
     61   carries taint. At the time of this writing, taint was only introduced by the
     62   checks under experimental.security.taint.TaintPropagation; this checker may
     63   eventually move to the security.taint package.
     64 
     65 - debug.ExprInspection: Responds to certain function calls, which are modeled
     66   after builtins. These function calls should affect the program state other
     67   than the evaluation of their arguments; to use them, you will need to declare
     68   them within your test file. The available functions are described below.
     69 
     70 (FIXME: debug.ExprInspection should probably be renamed, since it no longer only
     71 inspects expressions.)
     72 
     73 
     74 ExprInspection checks
     75 ---------------------
     76 
     77 - void clang_analyzer_eval(bool);
     78 
     79   Prints TRUE if the argument is known to have a non-zero value, FALSE if the
     80   argument is known to have a zero or null value, and UNKNOWN if the argument
     81   isn't sufficiently constrained on this path.  You can use this to test other
     82   values by using expressions like "x == 5".  Note that this functionality is
     83   currently DISABLED in inlined functions, since different calls to the same
     84   inlined function could provide different information, making it difficult to
     85   write proper -verify directives.
     86 
     87   In C, the argument can be typed as 'int' or as '_Bool'.
     88 
     89   Example usage::
     90 
     91     clang_analyzer_eval(x); // expected-warning{{UNKNOWN}}
     92     if (!x) return;
     93     clang_analyzer_eval(x); // expected-warning{{TRUE}}
     94 
     95 
     96 - void clang_analyzer_checkInlined(bool);
     97 
     98   If a call occurs within an inlined function, prints TRUE or FALSE according to
     99   the value of its argument. If a call occurs outside an inlined function,
    100   nothing is printed.
    101 
    102   The intended use of this checker is to assert that a function is inlined at
    103   least once (by passing 'true' and expecting a warning), or to assert that a
    104   function is never inlined (by passing 'false' and expecting no warning). The
    105   argument is technically unnecessary but is intended to clarify intent.
    106 
    107   You might wonder why we can't print TRUE if a function is ever inlined and
    108   FALSE if it is not. The problem is that any inlined function could conceivably
    109   also be analyzed as a top-level function (in which case both TRUE and FALSE
    110   would be printed), depending on the value of the -analyzer-inlining option.
    111 
    112   In C, the argument can be typed as 'int' or as '_Bool'.
    113 
    114   Example usage::
    115 
    116     int inlined() {
    117       clang_analyzer_checkInlined(true); // expected-warning{{TRUE}}
    118       return 42;
    119     }
    120     
    121     void topLevel() {
    122       clang_analyzer_checkInlined(false); // no-warning (not inlined)
    123       int value = inlined();
    124       // This assertion will not be valid if the previous call was not inlined.
    125       clang_analyzer_eval(value == 42); // expected-warning{{TRUE}}
    126     }
    127 
    128 - void clang_analyzer_warnIfReached();
    129 
    130   Generate a warning if this line of code gets reached by the analyzer.
    131 
    132   Example usage::
    133 
    134     if (true) {
    135       clang_analyzer_warnIfReached();  // expected-warning{{REACHABLE}}
    136     }
    137     else {
    138       clang_analyzer_warnIfReached();  // no-warning
    139     }
    140 
    141 
    142 Statistics
    143 ==========
    144 
    145 The debug.Stats checker collects various information about the analysis of each
    146 function, such as how many blocks were reached and if the analyzer timed out.
    147 
    148 There is also an additional -analyzer-stats flag, which enables various
    149 statistics within the analyzer engine. Note the Stats checker (which produces at
    150 least one bug report per function) may actually change the values reported by
    151 -analyzer-stats.
    152