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