1*e5dd7070Spatrick<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" 2*e5dd7070Spatrick "http://www.w3.org/TR/html4/strict.dtd"> 3*e5dd7070Spatrick<html> 4*e5dd7070Spatrick<head> 5*e5dd7070Spatrick <title>FAQ and How to Deal with Common False Positives</title> 6*e5dd7070Spatrick <link type="text/css" rel="stylesheet" href="menu.css"> 7*e5dd7070Spatrick <link type="text/css" rel="stylesheet" href="content.css"> 8*e5dd7070Spatrick <script type="text/javascript" src="scripts/menu.js"></script> 9*e5dd7070Spatrick <style type="text/css"> 10*e5dd7070Spatrick tr:first-child { width:20%; } 11*e5dd7070Spatrick </style> 12*e5dd7070Spatrick</head> 13*e5dd7070Spatrick<body> 14*e5dd7070Spatrick 15*e5dd7070Spatrick<div id="page"> 16*e5dd7070Spatrick<!--#include virtual="menu.html.incl"--> 17*e5dd7070Spatrick 18*e5dd7070Spatrick<div id="content"> 19*e5dd7070Spatrick 20*e5dd7070Spatrick<h1>FAQ and How to Deal with Common False Positives</h1> 21*e5dd7070Spatrick 22*e5dd7070Spatrick<ol> 23*e5dd7070Spatrick <li><a href="#custom_assert">How do I tell the analyzer that I do not want the bug being 24*e5dd7070Spatrickreported here since my custom error handler will safely end the execution before 25*e5dd7070Spatrickthe bug is reached?</a></li> 26*e5dd7070Spatrick <li><a href="#null_pointer">The analyzer reports a null dereference, but I know that the 27*e5dd7070Spatrickpointer is never null. How can I tell the analyzer that a pointer can never be 28*e5dd7070Spatricknull?</a></li> 29*e5dd7070Spatrick <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*e5dd7070Spatrick <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*e5dd7070Spatrick <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*e5dd7070Spatrick <li><a href="#dealloc_mrr">How do I tell the analyzer that my instance variable does not need to be released in -dealloc under Manual Retain/Release?</a></li> 33*e5dd7070Spatrick <li><a href="#decide_nullability">How do I decide whether a method's return type should be _Nullable or _Nonnull?</a></li> 34*e5dd7070Spatrick <li><a href="#nullability_intentional_violation">How do I tell the analyzer that I am intentionally violating nullability?</a></li> 35*e5dd7070Spatrick <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> 36*e5dd7070Spatrick <li><a href="#suppress_issue">How can I suppress a specific analyzer warning?</a></li> 37*e5dd7070Spatrick <li><a href="#exclude_code">How can I selectively exclude code the analyzer examines?</a></li> 38*e5dd7070Spatrick</ol> 39*e5dd7070Spatrick 40*e5dd7070Spatrick 41*e5dd7070Spatrick<h4 id="custom_assert" class="faq">Q: How do I tell the analyzer that I do not want the bug being 42*e5dd7070Spatrickreported here since my custom error handler will safely end the execution before 43*e5dd7070Spatrickthe bug is reached?</h4> 44*e5dd7070Spatrick 45*e5dd7070Spatrick<img src="images/example_custom_assert.png" alt="example custom assert"> 46*e5dd7070Spatrick 47*e5dd7070Spatrick<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> 48*e5dd7070Spatrick 49*e5dd7070Spatrick<pre class="code_example"> 50*e5dd7070Spatrickvoid customAssert() <span class="code_highlight">__attribute__((analyzer_noreturn))</span>; 51*e5dd7070Spatrickint foo(int *b) { 52*e5dd7070Spatrick if (!b) 53*e5dd7070Spatrick customAssert(); 54*e5dd7070Spatrick return *b; 55*e5dd7070Spatrick}</pre> 56*e5dd7070Spatrick 57*e5dd7070Spatrick 58*e5dd7070Spatrick<h4 id="null_pointer" class="faq">Q: The analyzer reports a null dereference, but I know that the 59*e5dd7070Spatrickpointer is never null. How can I tell the analyzer that a pointer can never be 60*e5dd7070Spatricknull?</h4> 61*e5dd7070Spatrick 62*e5dd7070Spatrick<img src="images/example_null_pointer.png" alt="example null pointer"> 63*e5dd7070Spatrick 64*e5dd7070Spatrick<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> 65*e5dd7070Spatrick 66*e5dd7070Spatrick<pre class="code_example"> 67*e5dd7070Spatrickvoid usePointer(int *b); 68*e5dd7070Spatrickint foo(int *b) { 69*e5dd7070Spatrick usePointer(b); 70*e5dd7070Spatrick return *b; 71*e5dd7070Spatrick}</pre> 72*e5dd7070Spatrick 73*e5dd7070Spatrick<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> 74*e5dd7070Spatrick 75*e5dd7070Spatrick<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: 76*e5dd7070Spatrick<pre class="code_example">Value stored to 'x' is never read</pre> 77*e5dd7070SpatrickYou 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> 78*e5dd7070Spatrick 79*e5dd7070Spatrick<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> 80*e5dd7070Spatrick 81*e5dd7070Spatrick<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: 82*e5dd7070Spatrick<pre class="code_example">Instance variable 'commonName' in class 'HappyBird' is never used by the methods in its @implementation</pre> 83*e5dd7070SpatrickYou can add <tt>__attribute__((unused))</tt> to the instance variable declaration to suppress the warning.</p> 84*e5dd7070Spatrick 85*e5dd7070Spatrick<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> 86*e5dd7070Spatrick 87*e5dd7070Spatrick<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: 88*e5dd7070Spatrick<pre class="code_example">User-facing text should use localized string macro</pre> 89*e5dd7070Spatrick 90*e5dd7070SpatrickIf 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: 91*e5dd7070Spatrick<pre class="code_example"> 92*e5dd7070Spatrick__attribute__((annotate("returns_localized_nsstring"))) 93*e5dd7070Spatrickstatic inline NSString *LocalizationNotNeeded(NSString *s) { 94*e5dd7070Spatrick return s; 95*e5dd7070Spatrick} 96*e5dd7070Spatrick</pre> 97*e5dd7070Spatrick 98*e5dd7070SpatrickYou can then call this function when creating your debugging UI: 99*e5dd7070Spatrick<pre class="code_example"> 100*e5dd7070Spatrick[field setStringValue:LocalizationNotNeeded(@"Debug")]; 101*e5dd7070Spatrick</pre> 102*e5dd7070Spatrick 103*e5dd7070SpatrickSome projects may also find it useful to use NSLocalizedString but add "DNL" or "Do Not Localize" to the string contents as a convention: 104*e5dd7070Spatrick<pre class="code_example"> 105*e5dd7070SpatrickUILabel *testLabel = [[UILabel alloc] init]; 106*e5dd7070SpatrickNSString *s = NSLocalizedString(@"Hello <Do Not Localize>", @"For debug purposes"); 107*e5dd7070Spatrick[testLabel setText:s]; 108*e5dd7070Spatrick</pre> 109*e5dd7070Spatrick</p> 110*e5dd7070Spatrick 111*e5dd7070Spatrick<h4 id="dealloc_mrr" class="faq">Q: How do I tell the analyzer that my instance variable does not need to be released in -dealloc under Manual Retain/Release?</h4> 112*e5dd7070Spatrick 113*e5dd7070Spatrick<p>If your class only uses an instance variable for part of its lifetime, it may 114*e5dd7070Spatrickmaintain an invariant guaranteeing that the instance variable is always released 115*e5dd7070Spatrickbefore -dealloc. In this case, you can silence a warning about a missing release 116*e5dd7070Spatrickby either adding <tt>assert(_ivar == nil)</tt> or an explicit release 117*e5dd7070Spatrick<tt>[_ivar release]</tt> (which will be a no-op when the variable is nil) in 118*e5dd7070Spatrick-dealloc. </p> 119*e5dd7070Spatrick 120*e5dd7070Spatrick<h4 id="decide_nullability" class="faq">Q: How do I decide whether a method's return type should be _Nullable or _Nonnull?</h4> 121*e5dd7070Spatrick 122*e5dd7070Spatrick<p> Depending on the implementation of the method, this puts you in one of five situations: 123*e5dd7070Spatrick<ol> 124*e5dd7070Spatrick<li>You actually never return nil.</li> 125*e5dd7070Spatrick<li>You do return nil sometimes, and callers are supposed to handle that. This 126*e5dd7070Spatrickincludes cases where your method is documented to return nil given certain 127*e5dd7070Spatrickinputs.</li> 128*e5dd7070Spatrick<li>You return nil based on some external condition (such as an out-of-memory 129*e5dd7070Spatrickerror), but the client can't do anything about it either.</li> 130*e5dd7070Spatrick<li>You return nil only when the caller passes input documented to be invalid. 131*e5dd7070SpatrickThat means it's the client's fault.</li> 132*e5dd7070Spatrick<li>You return nil in some totally undocumented case.</li> 133*e5dd7070Spatrick</ol> 134*e5dd7070Spatrick</p> 135*e5dd7070Spatrick 136*e5dd7070Spatrick<p>In (1) you should annotate the method as returning a <tt>_Nonnull</tt> 137*e5dd7070Spatrickobject.</p> 138*e5dd7070Spatrick<p>In (2) the method should be marked <tt>_Nullable.</tt></p> 139*e5dd7070Spatrick<p>In (3) you should probably annotate the method <tt>_Nonnull</tt>. Why? 140*e5dd7070SpatrickBecause no callers will actually check for nil, given that they can't do 141*e5dd7070Spatrickanything about the situation and don't know what went wrong. At this point 142*e5dd7070Spatrickthings have gone so poorly that there's basically no way to recover.</p> 143*e5dd7070Spatrick<p>The least happy case is (4) because the resulting program will almost 144*e5dd7070Spatrickcertainly either crash or just silently do the wrong thing. 145*e5dd7070SpatrickIf this is a new method or you control the callers, you can use 146*e5dd7070Spatrick<tt>NSParameterAssert()</tt> (or the equivalent) to check the precondition and 147*e5dd7070Spatrickremove the nil return. But if you don't control the callers and they rely on 148*e5dd7070Spatrickthis behavior, you should return mark the method <tt>_Nonnull</tt> and return 149*e5dd7070Spatricknil <a href="#nullability_intentional_violation">cast to _Nonnull</a> anyway. 150*e5dd7070Spatrick(Note that (4) doesn't apply in cases where the caller can't know they passed 151*e5dd7070Spatrickbad parameters. For example, 152*e5dd7070Spatrick<tt>+[NSData dataWithContentsOfFile:options:error:]</tt> will fail if the file 153*e5dd7070Spatrickdoesn't exist, but there's no way to check for that in advance. This means 154*e5dd7070Spatrickyou're really in (2).)</p> 155*e5dd7070Spatrick<p>If you're in (5), document it, then figure out if you're now in (2), (3), or 156*e5dd7070Spatrick(4). :-)</p> 157*e5dd7070Spatrick 158*e5dd7070Spatrick<h4 id="nullability_intentional_violation" class="faq">Q: How do I tell the analyzer that I am intentionally violating nullability?</h4> 159*e5dd7070Spatrick 160*e5dd7070Spatrick<p>In some cases, it may make sense for methods to intentionally violate 161*e5dd7070Spatricknullability. For example, your method may — for reasons of backward 162*e5dd7070Spatrickcompatibility — chose to return nil and log an error message in a method 163*e5dd7070Spatrickwith a non-null return type when the client violated a documented precondition 164*e5dd7070Spatrickrather than check the precondition with <tt>NSAssert()</tt>. In these cases, you 165*e5dd7070Spatrickcan suppress the analyzer warning with a cast: 166*e5dd7070Spatrick<pre class="code_example"> 167*e5dd7070Spatrick return (id _Nonnull)nil; 168*e5dd7070Spatrick</pre> 169*e5dd7070SpatrickNote that this cast does not affect code generation. 170*e5dd7070Spatrick</p> 171*e5dd7070Spatrick 172*e5dd7070Spatrick<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> 173*e5dd7070Spatrick 174*e5dd7070Spatrick<img src="images/example_use_assert.png" alt="example use assert"> 175*e5dd7070Spatrick 176*e5dd7070Spatrick<p> In the contrived example above, the analyzer has detected that the body of 177*e5dd7070Spatrickthe loop is never entered for the case where <tt>length <= 0</tt>. In this 178*e5dd7070Spatrickparticular example, you may know that the loop will always be entered because 179*e5dd7070Spatrickthe input parameter <tt>length</tt> will be greater than zero in all calls to this 180*e5dd7070Spatrickfunction. You can teach the analyzer facts about your code as well as document 181*e5dd7070Spatrickit by using assertions. By adding <tt>assert(length > 0)</tt> in the beginning 182*e5dd7070Spatrickof the function, you tell the analyzer that your code is never expecting a zero 183*e5dd7070Spatrickor a negative value, so it won't need to test the correctness of those paths. 184*e5dd7070Spatrick</p> 185*e5dd7070Spatrick 186*e5dd7070Spatrick<pre class="code_example"> 187*e5dd7070Spatrickint foo(int length) { 188*e5dd7070Spatrick int x = 0; 189*e5dd7070Spatrick <span class="code_highlight">assert(length > 0);</span> 190*e5dd7070Spatrick for (int i = 0; i < length; i++) 191*e5dd7070Spatrick x += 1; 192*e5dd7070Spatrick return length/x; 193*e5dd7070Spatrick} 194*e5dd7070Spatrick</pre> 195*e5dd7070Spatrick 196*e5dd7070Spatrick<h4 id="suppress_issue" class="faq">Q: How can I suppress a specific analyzer warning?</h4> 197*e5dd7070Spatrick 198*e5dd7070Spatrick<p>There is currently no solid mechanism for suppressing an analyzer warning, 199*e5dd7070Spatrickalthough this is currently being investigated. When you encounter an analyzer 200*e5dd7070Spatrickbug/false positive, check if it's one of the issues discussed above or if the 201*e5dd7070Spatrickanalyzer <a href = "annotations.html#custom_assertions" >annotations</a> can 202*e5dd7070Spatrickresolve the issue. Second, please <a href = "filing_bugs.html">report it</a> to 203*e5dd7070Spatrickhelp us improve user experience. As the last resort, consider using <tt>__clang_analyzer__</tt> macro 204*e5dd7070Spatrick<a href = "faq.html#exclude_code" >described below</a>.</p> 205*e5dd7070Spatrick 206*e5dd7070Spatrick<h4 id="exclude_code" class="faq">Q: How can I selectively exclude code the analyzer examines?</h4> 207*e5dd7070Spatrick 208*e5dd7070Spatrick<p>When the static analyzer is using clang to parse source files, it implicitly 209*e5dd7070Spatrickdefines the preprocessor macro <tt>__clang_analyzer__</tt>. One can use this 210*e5dd7070Spatrickmacro to selectively exclude code the analyzer examines. Here is an example: 211*e5dd7070Spatrick 212*e5dd7070Spatrick<pre class="code_example"> 213*e5dd7070Spatrick#ifndef __clang_analyzer__ 214*e5dd7070Spatrick// Code not to be analyzed 215*e5dd7070Spatrick#endif 216*e5dd7070Spatrick</pre> 217*e5dd7070Spatrick 218*e5dd7070SpatrickThis usage is discouraged because it makes the code dead to the analyzer from 219*e5dd7070Spatricknow on. Instead, we prefer that users file bugs against the analyzer when it flags 220*e5dd7070Spatrickfalse positives. 221*e5dd7070Spatrick</p> 222*e5dd7070Spatrick 223*e5dd7070Spatrick</div> 224*e5dd7070Spatrick</div> 225*e5dd7070Spatrick</body> 226*e5dd7070Spatrick</html> 227
