1*f4a2713aSLionel Sambuc<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" 2*f4a2713aSLionel Sambuc "http://www.w3.org/TR/html4/strict.dtd"> 3*f4a2713aSLionel Sambuc<html> 4*f4a2713aSLionel Sambuc<head> 5*f4a2713aSLionel Sambuc <title>FAQ and How to Deal with Common False Positives</title> 6*f4a2713aSLionel Sambuc <link type="text/css" rel="stylesheet" href="menu.css"> 7*f4a2713aSLionel Sambuc <link type="text/css" rel="stylesheet" href="content.css"> 8*f4a2713aSLionel Sambuc <script type="text/javascript" src="scripts/menu.js"></script> 9*f4a2713aSLionel Sambuc <style type="text/css"> 10*f4a2713aSLionel Sambuc tr:first-child { width:20%; } 11*f4a2713aSLionel Sambuc </style> 12*f4a2713aSLionel Sambuc</head> 13*f4a2713aSLionel Sambuc<body> 14*f4a2713aSLionel Sambuc 15*f4a2713aSLionel Sambuc<div id="page"> 16*f4a2713aSLionel Sambuc<!--#include virtual="menu.html.incl"--> 17*f4a2713aSLionel Sambuc 18*f4a2713aSLionel Sambuc<div id="content"> 19*f4a2713aSLionel Sambuc 20*f4a2713aSLionel Sambuc<h1>FAQ and How to Deal with Common False Positives</h1> 21*f4a2713aSLionel Sambuc 22*f4a2713aSLionel Sambuc<ol> 23*f4a2713aSLionel Sambuc <li><a href="#custom_assert">How do I tell the analyzer that I do not want the bug being 24*f4a2713aSLionel Sambucreported here since my custom error handler will safely end the execution before 25*f4a2713aSLionel Sambucthe bug is reached?</a></li> 26*f4a2713aSLionel Sambuc <li><a href="#null_pointer">The analyzer reports a null dereference, but I know that the 27*f4a2713aSLionel Sambucpointer is never null. How can I tell the analyzer that a pointer can never be 28*f4a2713aSLionel Sambucnull?</a></li> 29*f4a2713aSLionel Sambuc <li><a href="#use_assert">The analyzer assumes that a loop body is never entered. How can I tell it that the loop body will be entered at least once?</a></li> 30*f4a2713aSLionel Sambuc <li><a href="#suppress_issue">How can I suppress a specific analyzer warning?</a></li> 31*f4a2713aSLionel Sambuc <li><a href="#exclude_code">How can I selectively exclude code the analyzer examines?</a></li> 32*f4a2713aSLionel Sambuc</ol> 33*f4a2713aSLionel Sambuc 34*f4a2713aSLionel Sambuc 35*f4a2713aSLionel Sambuc<h4 id="custom_assert" class="faq">Q: How do I tell the analyzer that I do not want the bug being 36*f4a2713aSLionel Sambucreported here since my custom error handler will safely end the execution before 37*f4a2713aSLionel Sambucthe bug is reached?</h4> 38*f4a2713aSLionel Sambuc 39*f4a2713aSLionel Sambuc<img src="images/example_custom_assert.png" alt="example custom assert"> 40*f4a2713aSLionel Sambuc 41*f4a2713aSLionel Sambuc<p>You can tell the analyzer that this path is unreachable by teaching it about your <a href = "annotations.html#custom_assertions" >custom assertion handlers</a>. For example, you can modify the code segment as following.</p> 42*f4a2713aSLionel Sambuc 43*f4a2713aSLionel Sambuc<pre class="code_example"> 44*f4a2713aSLionel Sambucvoid customAssert() <span class="code_highlight">__attribute__((analyzer_noreturn))</span>; 45*f4a2713aSLionel Sambucint foo(int *b) { 46*f4a2713aSLionel Sambuc if (!b) 47*f4a2713aSLionel Sambuc customAssert(); 48*f4a2713aSLionel Sambuc return *b; 49*f4a2713aSLionel Sambuc}</pre> 50*f4a2713aSLionel Sambuc 51*f4a2713aSLionel Sambuc 52*f4a2713aSLionel Sambuc<h4 id="null_pointer" class="faq">Q: The analyzer reports a null dereference, but I know that the 53*f4a2713aSLionel Sambucpointer is never null. How can I tell the analyzer that a pointer can never be 54*f4a2713aSLionel Sambucnull?</h4> 55*f4a2713aSLionel Sambuc 56*f4a2713aSLionel Sambuc<img src="images/example_null_pointer.png" alt="example null pointer"> 57*f4a2713aSLionel Sambuc 58*f4a2713aSLionel Sambuc<p>The reason the analyzer often thinks that a pointer can be null is because the preceding code checked compared it against null. So if you are absolutely sure that it cannot be null, remove the preceding check and, preferably, add an assertion as well. For example, in the code segment above, it will be sufficient to remove the <tt>if (!b)</tt> check. </p> 59*f4a2713aSLionel Sambuc 60*f4a2713aSLionel Sambuc<pre class="code_example"> 61*f4a2713aSLionel Sambucvoid usePointer(int *b); 62*f4a2713aSLionel Sambucint foo(int *b) { 63*f4a2713aSLionel Sambuc usePointer(b); 64*f4a2713aSLionel Sambuc return *b; 65*f4a2713aSLionel Sambuc}</pre> 66*f4a2713aSLionel Sambuc 67*f4a2713aSLionel Sambuc<h4 id="use_assert" class="faq">Q: The analyzer assumes that a loop body is never entered. How can I tell it that the loop body will be entered at least once?</h4> 68*f4a2713aSLionel Sambuc 69*f4a2713aSLionel Sambuc<img src="images/example_use_assert.png" alt="example use assert"> 70*f4a2713aSLionel Sambuc 71*f4a2713aSLionel Sambuc<p> In the contrived example above, the analyzer has detected that the body of 72*f4a2713aSLionel Sambucthe loop is never entered for the case where <tt>length <= 0</tt>. In this 73*f4a2713aSLionel Sambucparticular example, you may know that the loop will always be entered because 74*f4a2713aSLionel Sambucthe input parameter <tt>length</tt> will be greater than zero in all calls to this 75*f4a2713aSLionel Sambucfunction. You can teach the analyzer facts about your code as well as document 76*f4a2713aSLionel Sambucit by using assertions. By adding <tt>assert(length > 0)</tt> in the beginning 77*f4a2713aSLionel Sambucof the function, you tell the analyzer that your code is never expecting a zero 78*f4a2713aSLionel Sambucor a negative value, so it won't need to test the correctness of those paths. 79*f4a2713aSLionel Sambuc</p> 80*f4a2713aSLionel Sambuc 81*f4a2713aSLionel Sambuc<pre class="code_example"> 82*f4a2713aSLionel Sambucint foo(int length) { 83*f4a2713aSLionel Sambuc int x = 0; 84*f4a2713aSLionel Sambuc <span class="code_highlight">assert(length > 0);</span> 85*f4a2713aSLionel Sambuc for (int i = 0; i < length; i++) 86*f4a2713aSLionel Sambuc x += 1; 87*f4a2713aSLionel Sambuc return length/x; 88*f4a2713aSLionel Sambuc} 89*f4a2713aSLionel Sambuc</pre> 90*f4a2713aSLionel Sambuc 91*f4a2713aSLionel Sambuc<h4 id="suppress_issue" class="faq">Q: How can I suppress a specific analyzer warning?</h4> 92*f4a2713aSLionel Sambuc 93*f4a2713aSLionel Sambuc<p>There is currently no solid mechanism for suppressing an analyzer warning, 94*f4a2713aSLionel Sambucalthough this is currently being investigated. When you encounter an analyzer 95*f4a2713aSLionel Sambucbug/false positive, check if it's one of the issues discussed above or if the 96*f4a2713aSLionel Sambucanalyzer <a href = "annotations.html#custom_assertions" >annotations</a> can 97*f4a2713aSLionel Sambucresolve the issue. Second, please <a href = "filing_bugs.html">report it</a> to 98*f4a2713aSLionel Sambuchelp us improve user experience. As the last resort, consider using <tt>__clang_analyzer__</tt> macro 99*f4a2713aSLionel Sambuc<a href = "faq.html#exclude_code" >described below</a>.</p> 100*f4a2713aSLionel Sambuc 101*f4a2713aSLionel Sambuc<h4 id="exclude_code" class="faq">Q: How can I selectively exclude code the analyzer examines?</h4> 102*f4a2713aSLionel Sambuc 103*f4a2713aSLionel Sambuc<p>When the static analyzer is using clang to parse source files, it implicitly 104*f4a2713aSLionel Sambucdefines the preprocessor macro <tt>__clang_analyzer__</tt>. One can use this 105*f4a2713aSLionel Sambucmacro to selectively exclude code the analyzer examines. Here is an example: 106*f4a2713aSLionel Sambuc 107*f4a2713aSLionel Sambuc<pre class="code_example"> 108*f4a2713aSLionel Sambuc#ifndef __clang_analyzer__ 109*f4a2713aSLionel Sambuc// Code not to be analyzed 110*f4a2713aSLionel Sambuc#endif 111*f4a2713aSLionel Sambuc</pre> 112*f4a2713aSLionel Sambuc 113*f4a2713aSLionel SambucThis usage is discouraged because it makes the code dead to the analyzer from 114*f4a2713aSLionel Sambucnow on. Instead, we prefer that users file bugs against the analyzer when it flags 115*f4a2713aSLionel Sambucfalse positives. 116*f4a2713aSLionel Sambuc</p> 117*f4a2713aSLionel Sambuc 118*f4a2713aSLionel Sambuc</div> 119*f4a2713aSLionel Sambuc</div> 120*f4a2713aSLionel Sambuc</body> 121*f4a2713aSLionel Sambuc</html> 122*f4a2713aSLionel Sambuc 123
