1*67e74705SXin Li<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" 2*67e74705SXin Li "http://www.w3.org/TR/html4/strict.dtd"> 3*67e74705SXin Li<html> 4*67e74705SXin Li<head> 5*67e74705SXin Li <title>FAQ and How to Deal with Common False Positives</title> 6*67e74705SXin Li <link type="text/css" rel="stylesheet" href="menu.css"> 7*67e74705SXin Li <link type="text/css" rel="stylesheet" href="content.css"> 8*67e74705SXin Li <script type="text/javascript" src="scripts/menu.js"></script> 9*67e74705SXin Li <style type="text/css"> 10*67e74705SXin Li tr:first-child { width:20%; } 11*67e74705SXin Li </style> 12*67e74705SXin Li</head> 13*67e74705SXin Li<body> 14*67e74705SXin Li 15*67e74705SXin Li<div id="page"> 16*67e74705SXin Li<!--#include virtual="menu.html.incl"--> 17*67e74705SXin Li 18*67e74705SXin Li<div id="content"> 19*67e74705SXin Li 20*67e74705SXin Li<h1>FAQ and How to Deal with Common False Positives</h1> 21*67e74705SXin Li 22*67e74705SXin Li<ol> 23*67e74705SXin Li <li><a href="#custom_assert">How do I tell the analyzer that I do not want the bug being 24*67e74705SXin Lireported here since my custom error handler will safely end the execution before 25*67e74705SXin Lithe bug is reached?</a></li> 26*67e74705SXin Li <li><a href="#null_pointer">The analyzer reports a null dereference, but I know that the 27*67e74705SXin Lipointer is never null. How can I tell the analyzer that a pointer can never be 28*67e74705SXin Linull?</a></li> 29*67e74705SXin Li <li><a href="#dead_store">How do I tell the static analyzer that I don't care about a specific dead store?</a></li> 30*67e74705SXin Li <li><a href="#unused_ivar">How do I tell the static analyzer that I don't care about a specific unused instance variable in Objective C?</a></li> 31*67e74705SXin Li <li><a href="#unlocalized_string">How do I tell the static analyzer that I don't care about a specific unlocalized string?</a></li> 32*67e74705SXin Li <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> 33*67e74705SXin Li <li><a href="#suppress_issue">How can I suppress a specific analyzer warning?</a></li> 34*67e74705SXin Li <li><a href="#exclude_code">How can I selectively exclude code the analyzer examines?</a></li> 35*67e74705SXin Li</ol> 36*67e74705SXin Li 37*67e74705SXin Li 38*67e74705SXin Li<h4 id="custom_assert" class="faq">Q: How do I tell the analyzer that I do not want the bug being 39*67e74705SXin Lireported here since my custom error handler will safely end the execution before 40*67e74705SXin Lithe bug is reached?</h4> 41*67e74705SXin Li 42*67e74705SXin Li<img src="images/example_custom_assert.png" alt="example custom assert"> 43*67e74705SXin Li 44*67e74705SXin Li<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> 45*67e74705SXin Li 46*67e74705SXin Li<pre class="code_example"> 47*67e74705SXin Livoid customAssert() <span class="code_highlight">__attribute__((analyzer_noreturn))</span>; 48*67e74705SXin Liint foo(int *b) { 49*67e74705SXin Li if (!b) 50*67e74705SXin Li customAssert(); 51*67e74705SXin Li return *b; 52*67e74705SXin Li}</pre> 53*67e74705SXin Li 54*67e74705SXin Li 55*67e74705SXin Li<h4 id="null_pointer" class="faq">Q: The analyzer reports a null dereference, but I know that the 56*67e74705SXin Lipointer is never null. How can I tell the analyzer that a pointer can never be 57*67e74705SXin Linull?</h4> 58*67e74705SXin Li 59*67e74705SXin Li<img src="images/example_null_pointer.png" alt="example null pointer"> 60*67e74705SXin Li 61*67e74705SXin Li<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> 62*67e74705SXin Li 63*67e74705SXin Li<pre class="code_example"> 64*67e74705SXin Livoid usePointer(int *b); 65*67e74705SXin Liint foo(int *b) { 66*67e74705SXin Li usePointer(b); 67*67e74705SXin Li return *b; 68*67e74705SXin Li}</pre> 69*67e74705SXin Li 70*67e74705SXin Li<h4 id="dead_store" class="faq">Q: How do I tell the static analyzer that I don't care about a specific dead store?</h4> 71*67e74705SXin Li 72*67e74705SXin Li<p>When the analyzer sees that a value stored into a variable is never used, it's going to produce a message similar to this one: 73*67e74705SXin Li<pre class="code_example">Value stored to 'x' is never read</pre> 74*67e74705SXin LiYou can use the <tt>(void)x;</tt> idiom to acknowledge that there is a dead store in your code but you do not want it to be reported in the future.</p> 75*67e74705SXin Li 76*67e74705SXin Li<h4 id="unused_ivar" class="faq">Q: How do I tell the static analyzer that I don't care about a specific unused instance variable in Objective C?</h4> 77*67e74705SXin Li 78*67e74705SXin Li<p>When the analyzer sees that a value stored into a variable is never used, it is going to produce a message similar to this one: 79*67e74705SXin Li<pre class="code_example">Instance variable 'commonName' in class 'HappyBird' is never used by the methods in its @implementation</pre> 80*67e74705SXin LiYou can add <tt>__attribute__((unused))</tt> to the instance variable declaration to suppress the warning.</p> 81*67e74705SXin Li 82*67e74705SXin Li<h4 id="unlocalized_string" class="faq">Q: How do I tell the static analyzer that I don't care about a specific unlocalized string?</h4> 83*67e74705SXin Li 84*67e74705SXin Li<p>When the analyzer sees that an unlocalized string is passed to a method that will present that string to the user, it is going to produce a message similar to this one: 85*67e74705SXin Li<pre class="code_example">User-facing text should use localized string macro</pre> 86*67e74705SXin Li 87*67e74705SXin LiIf your project deliberately uses unlocalized user-facing strings (for example, in a debugging UI that is never shown to users), you can suppress the analyzer warnings (and document your intent) with a function that just returns its input but is annotated to return a localized string: 88*67e74705SXin Li<pre class="code_example"> 89*67e74705SXin Li__attribute__((annotate("returns_localized_nsstring"))) 90*67e74705SXin Listatic inline NSString *LocalizationNotNeeded(NSString *s) { 91*67e74705SXin Li return s; 92*67e74705SXin Li} 93*67e74705SXin Li</pre> 94*67e74705SXin Li 95*67e74705SXin LiYou can then call this function when creating your debugging UI: 96*67e74705SXin Li<pre class="code_example"> 97*67e74705SXin Li[field setStringValue:LocalizationNotNeeded(@"Debug")]; 98*67e74705SXin Li</pre> 99*67e74705SXin Li 100*67e74705SXin LiSome projects may also find it useful to use NSLocalizedString but add "DNL" or "Do Not Localize" to the string contents as a convention: 101*67e74705SXin Li<pre class="code_example"> 102*67e74705SXin LiUILabel *testLabel = [[UILabel alloc] init]; 103*67e74705SXin LiNSString *s = NSLocalizedString(@"Hello <Do Not Localize>", @"For debug purposes"); 104*67e74705SXin Li[testLabel setText:s]; 105*67e74705SXin Li</pre> 106*67e74705SXin Li</p> 107*67e74705SXin Li 108*67e74705SXin Li<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> 109*67e74705SXin Li 110*67e74705SXin Li<img src="images/example_use_assert.png" alt="example use assert"> 111*67e74705SXin Li 112*67e74705SXin Li<p> In the contrived example above, the analyzer has detected that the body of 113*67e74705SXin Lithe loop is never entered for the case where <tt>length <= 0</tt>. In this 114*67e74705SXin Liparticular example, you may know that the loop will always be entered because 115*67e74705SXin Lithe input parameter <tt>length</tt> will be greater than zero in all calls to this 116*67e74705SXin Lifunction. You can teach the analyzer facts about your code as well as document 117*67e74705SXin Liit by using assertions. By adding <tt>assert(length > 0)</tt> in the beginning 118*67e74705SXin Liof the function, you tell the analyzer that your code is never expecting a zero 119*67e74705SXin Lior a negative value, so it won't need to test the correctness of those paths. 120*67e74705SXin Li</p> 121*67e74705SXin Li 122*67e74705SXin Li<pre class="code_example"> 123*67e74705SXin Liint foo(int length) { 124*67e74705SXin Li int x = 0; 125*67e74705SXin Li <span class="code_highlight">assert(length > 0);</span> 126*67e74705SXin Li for (int i = 0; i < length; i++) 127*67e74705SXin Li x += 1; 128*67e74705SXin Li return length/x; 129*67e74705SXin Li} 130*67e74705SXin Li</pre> 131*67e74705SXin Li 132*67e74705SXin Li<h4 id="suppress_issue" class="faq">Q: How can I suppress a specific analyzer warning?</h4> 133*67e74705SXin Li 134*67e74705SXin Li<p>There is currently no solid mechanism for suppressing an analyzer warning, 135*67e74705SXin Lialthough this is currently being investigated. When you encounter an analyzer 136*67e74705SXin Libug/false positive, check if it's one of the issues discussed above or if the 137*67e74705SXin Lianalyzer <a href = "annotations.html#custom_assertions" >annotations</a> can 138*67e74705SXin Liresolve the issue. Second, please <a href = "filing_bugs.html">report it</a> to 139*67e74705SXin Lihelp us improve user experience. As the last resort, consider using <tt>__clang_analyzer__</tt> macro 140*67e74705SXin Li<a href = "faq.html#exclude_code" >described below</a>.</p> 141*67e74705SXin Li 142*67e74705SXin Li<h4 id="exclude_code" class="faq">Q: How can I selectively exclude code the analyzer examines?</h4> 143*67e74705SXin Li 144*67e74705SXin Li<p>When the static analyzer is using clang to parse source files, it implicitly 145*67e74705SXin Lidefines the preprocessor macro <tt>__clang_analyzer__</tt>. One can use this 146*67e74705SXin Limacro to selectively exclude code the analyzer examines. Here is an example: 147*67e74705SXin Li 148*67e74705SXin Li<pre class="code_example"> 149*67e74705SXin Li#ifndef __clang_analyzer__ 150*67e74705SXin Li// Code not to be analyzed 151*67e74705SXin Li#endif 152*67e74705SXin Li</pre> 153*67e74705SXin Li 154*67e74705SXin LiThis usage is discouraged because it makes the code dead to the analyzer from 155*67e74705SXin Linow on. Instead, we prefer that users file bugs against the analyzer when it flags 156*67e74705SXin Lifalse positives. 157*67e74705SXin Li</p> 158*67e74705SXin Li 159*67e74705SXin Li</div> 160*67e74705SXin Li</div> 161*67e74705SXin Li</body> 162*67e74705SXin Li</html> 163*67e74705SXin Li 164
