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>Source Annotations</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</head> 10*67e74705SXin Li<body> 11*67e74705SXin Li 12*67e74705SXin Li<div id="page"> 13*67e74705SXin Li<!--#include virtual="menu.html.incl"--> 14*67e74705SXin Li 15*67e74705SXin Li<div id="content"> 16*67e74705SXin Li 17*67e74705SXin Li<h1>Source Annotations</h1> 18*67e74705SXin Li 19*67e74705SXin Li<p>The Clang frontend supports several source-level annotations in the form of 20*67e74705SXin Li<a href="http://gcc.gnu.org/onlinedocs/gcc/Attribute-Syntax.html">GCC-style 21*67e74705SXin Liattributes</a> and pragmas that can help make using the Clang Static Analyzer 22*67e74705SXin Limore useful. These annotations can both help suppress false positives as well as 23*67e74705SXin Lienhance the analyzer's ability to find bugs.</p> 24*67e74705SXin Li 25*67e74705SXin Li<p>This page gives a practical overview of such annotations. For more technical 26*67e74705SXin Lispecifics regarding Clang-specific annotations please see the Clang's list of <a 27*67e74705SXin Lihref="http://clang.llvm.org/docs/LanguageExtensions.html">language 28*67e74705SXin Liextensions</a>. Details of "standard" GCC attributes (that Clang also 29*67e74705SXin Lisupports) can be found in the <a href="http://gcc.gnu.org/onlinedocs/gcc/">GCC 30*67e74705SXin Limanual</a>, with the majority of the relevant attributes being in the section on 31*67e74705SXin Li<a href="http://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html">function 32*67e74705SXin Liattributes</a>.</p> 33*67e74705SXin Li 34*67e74705SXin Li<p>Note that attributes that are labeled <b>Clang-specific</b> are not 35*67e74705SXin Lirecognized by GCC. Their use can be conditioned using preprocessor macros 36*67e74705SXin Li(examples included on this page).</p> 37*67e74705SXin Li 38*67e74705SXin Li<h4>Specific Topics</h4> 39*67e74705SXin Li 40*67e74705SXin Li<ul> 41*67e74705SXin Li<li><a href="#generic">Annotations to Enhance Generic Checks</a> 42*67e74705SXin Li <ul> 43*67e74705SXin Li <li><a href="#null_checking"><span>Null Pointer Checking</span></a> 44*67e74705SXin Li <ul> 45*67e74705SXin Li <li><a href="#attr_nonnull"><span>Attribute 'nonnull'</span></a></li> 46*67e74705SXin Li </ul> 47*67e74705SXin Li </li> 48*67e74705SXin Li </ul> 49*67e74705SXin Li</li> 50*67e74705SXin Li<li><a href="#macosx">Mac OS X API Annotations</a> 51*67e74705SXin Li <ul> 52*67e74705SXin Li <li><a href="#cocoa_mem">Cocoa & Core Foundation Memory Management Annotations</a> 53*67e74705SXin Li <ul> 54*67e74705SXin Li <li><a href="#attr_ns_returns_retained">Attribute 'ns_returns_retained'</a></li> 55*67e74705SXin Li <li><a href="#attr_ns_returns_not_retained">Attribute 'ns_returns_not_retained'</a></li> 56*67e74705SXin Li <li><a href="#attr_cf_returns_retained">Attribute 'cf_returns_retained'</a></li> 57*67e74705SXin Li <li><a href="#attr_cf_returns_not_retained">Attribute 'cf_returns_not_retained'</a></li> 58*67e74705SXin Li <li><a href="#attr_ns_consumed">Attribute 'ns_consumed'</a></li> 59*67e74705SXin Li <li><a href="#attr_cf_consumed">Attribute 'cf_consumed'</a></li> 60*67e74705SXin Li <li><a href="#attr_ns_consumes_self">Attribute 'ns_consumes_self'</a></li> 61*67e74705SXin Li </ul> 62*67e74705SXin Li </li> 63*67e74705SXin Li </ul> 64*67e74705SXin Li</li> 65*67e74705SXin Li<li><a href="#custom_assertions">Custom Assertion Handlers</a> 66*67e74705SXin Li <ul> 67*67e74705SXin Li <li><a href="#attr_noreturn">Attribute 'noreturn'</a></li> 68*67e74705SXin Li <li><a href="#attr_analyzer_noreturn">Attribute 'analyzer_noreturn'</a></li> 69*67e74705SXin Li </ul> 70*67e74705SXin Li </li> 71*67e74705SXin Li</ul> 72*67e74705SXin Li 73*67e74705SXin Li<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> 74*67e74705SXin Li<h2 id="generic">Annotations to Enhance Generic Checks</h2> 75*67e74705SXin Li<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> 76*67e74705SXin Li 77*67e74705SXin Li<h3 id="null_checking">Null Pointer Checking</h3> 78*67e74705SXin Li 79*67e74705SXin Li<h4 id="attr_nonnull">Attribute 'nonnull'</h4> 80*67e74705SXin Li 81*67e74705SXin Li<p>The analyzer recognizes the GCC attribute 'nonnull', which indicates that a 82*67e74705SXin Lifunction expects that a given function parameter is not a null pointer. Specific 83*67e74705SXin Lidetails of the syntax of using the 'nonnull' attribute can be found in <a 84*67e74705SXin Lihref="http://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html#index-g_t_0040code_007bnonnull_007d-function-attribute-2263">GCC's 85*67e74705SXin Lidocumentation</a>.</p> 86*67e74705SXin Li 87*67e74705SXin Li<p>Both the Clang compiler and GCC will flag warnings for simple cases where a 88*67e74705SXin Linull pointer is directly being passed to a function with a 'nonnull' parameter 89*67e74705SXin Li(e.g., as a constant). The analyzer extends this checking by using its deeper 90*67e74705SXin Lisymbolic analysis to track what pointer values are potentially null and then 91*67e74705SXin Liflag warnings when they are passed in a function call via a 'nonnull' 92*67e74705SXin Liparameter.</p> 93*67e74705SXin Li 94*67e74705SXin Li<p><b>Example</b></p> 95*67e74705SXin Li 96*67e74705SXin Li<pre class="code_example"> 97*67e74705SXin Li<span class="command">$ cat test.m</span> 98*67e74705SXin Liint bar(int*p, int q, int *r) __attribute__((nonnull(1,3))); 99*67e74705SXin Li 100*67e74705SXin Liint foo(int *p, int *q) { 101*67e74705SXin Li return !p ? bar(q, 2, p) 102*67e74705SXin Li : bar(p, 2, q); 103*67e74705SXin Li} 104*67e74705SXin Li</pre> 105*67e74705SXin Li 106*67e74705SXin Li<p>Running <tt>scan-build</tt> over this source produces the following 107*67e74705SXin Lioutput:</p> 108*67e74705SXin Li 109*67e74705SXin Li<img src="images/example_attribute_nonnull.png" alt="example attribute nonnull"> 110*67e74705SXin Li 111*67e74705SXin Li<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> 112*67e74705SXin Li<h2 id="macosx">Mac OS X API Annotations</h2> 113*67e74705SXin Li<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> 114*67e74705SXin Li 115*67e74705SXin Li<h3 id="cocoa_mem">Cocoa & Core Foundation Memory Management 116*67e74705SXin LiAnnotations</h3> 117*67e74705SXin Li 118*67e74705SXin Li<!-- 119*67e74705SXin Li<p>As described in <a href="/available_checks.html#retain_release">Available 120*67e74705SXin LiChecks</a>, 121*67e74705SXin Li--> 122*67e74705SXin Li<p>The analyzer supports the proper management of retain counts for 123*67e74705SXin Liboth Cocoa and Core Foundation objects. This checking is largely based on 124*67e74705SXin Lienforcing Cocoa and Core Foundation naming conventions for Objective-C methods 125*67e74705SXin Li(Cocoa) and C functions (Core Foundation). Not strictly following these 126*67e74705SXin Liconventions can cause the analyzer to miss bugs or flag false positives.</p> 127*67e74705SXin Li 128*67e74705SXin Li<p>One can educate the analyzer (and others who read your code) about methods or 129*67e74705SXin Lifunctions that deviate from the Cocoa and Core Foundation conventions using the 130*67e74705SXin Liattributes described here. However, you should consider using proper naming 131*67e74705SXin Liconventions or the <a 132*67e74705SXin Lihref="http://clang.llvm.org/docs/LanguageExtensions.html#the-objc-method-family-attribute"><tt>objc_method_family</tt></a> 133*67e74705SXin Liattribute, if applicable.</p> 134*67e74705SXin Li 135*67e74705SXin Li<h4 id="attr_ns_returns_retained">Attribute 'ns_returns_retained' 136*67e74705SXin Li(Clang-specific)</h4> 137*67e74705SXin Li 138*67e74705SXin Li<p>The GCC-style (Clang-specific) attribute 'ns_returns_retained' allows one to 139*67e74705SXin Liannotate an Objective-C method or C function as returning a retained Cocoa 140*67e74705SXin Liobject that the caller is responsible for releasing (via sending a 141*67e74705SXin Li<tt>release</tt> message to the object). The Foundation framework defines a 142*67e74705SXin Limacro <b><tt>NS_RETURNS_RETAINED</tt></b> that is functionally equivalent to the 143*67e74705SXin Lione shown below.</p> 144*67e74705SXin Li 145*67e74705SXin Li<p><b>Placing on Objective-C methods</b>: For Objective-C methods, this 146*67e74705SXin Liannotation essentially tells the analyzer to treat the method as if its name 147*67e74705SXin Libegins with "alloc" or "new" or contains the word 148*67e74705SXin Li"copy".</p> 149*67e74705SXin Li 150*67e74705SXin Li<p><b>Placing on C functions</b>: For C functions returning Cocoa objects, the 151*67e74705SXin Lianalyzer typically does not make any assumptions about whether or not the object 152*67e74705SXin Liis returned retained. Explicitly adding the 'ns_returns_retained' attribute to C 153*67e74705SXin Lifunctions allows the analyzer to perform extra checking.</p> 154*67e74705SXin Li 155*67e74705SXin Li<p><b>Important note when using Garbage Collection</b>: Note that the analyzer 156*67e74705SXin Liinterprets this attribute slightly differently when using Objective-C garbage 157*67e74705SXin Licollection (available on Mac OS 10.5+). When analyzing Cocoa code that uses 158*67e74705SXin Ligarbage collection, "alloc" methods are assumed to return an object 159*67e74705SXin Lithat is managed by the garbage collector (and thus doesn't have a retain count 160*67e74705SXin Lithe caller must balance). These same assumptions are applied to methods or 161*67e74705SXin Lifunctions annotated with 'ns_returns_retained'. If you are returning a Core 162*67e74705SXin LiFoundation object (which may not be managed by the garbage collector) you should 163*67e74705SXin Liuse 'cf_returns_retained'.</p> 164*67e74705SXin Li 165*67e74705SXin Li<p><b>Example</b></p> 166*67e74705SXin Li 167*67e74705SXin Li<pre class="code_example"> 168*67e74705SXin Li<span class="command">$ cat test.m</span> 169*67e74705SXin Li#import <Foundation/Foundation.h> 170*67e74705SXin Li 171*67e74705SXin Li#ifndef __has_feature // Optional. 172*67e74705SXin Li#define __has_feature(x) 0 // Compatibility with non-clang compilers. 173*67e74705SXin Li#endif 174*67e74705SXin Li 175*67e74705SXin Li#ifndef NS_RETURNS_RETAINED 176*67e74705SXin Li#if __has_feature(attribute_ns_returns_retained) 177*67e74705SXin Li<span class="code_highlight">#define NS_RETURNS_RETAINED __attribute__((ns_returns_retained))</span> 178*67e74705SXin Li#else 179*67e74705SXin Li#define NS_RETURNS_RETAINED 180*67e74705SXin Li#endif 181*67e74705SXin Li#endif 182*67e74705SXin Li 183*67e74705SXin Li@interface MyClass : NSObject {} 184*67e74705SXin Li- (NSString*) returnsRetained <span class="code_highlight">NS_RETURNS_RETAINED</span>; 185*67e74705SXin Li- (NSString*) alsoReturnsRetained; 186*67e74705SXin Li@end 187*67e74705SXin Li 188*67e74705SXin Li@implementation MyClass 189*67e74705SXin Li- (NSString*) returnsRetained { 190*67e74705SXin Li return [[NSString alloc] initWithCString:"no leak here"]; 191*67e74705SXin Li} 192*67e74705SXin Li- (NSString*) alsoReturnsRetained { 193*67e74705SXin Li return [[NSString alloc] initWithCString:"flag a leak"]; 194*67e74705SXin Li} 195*67e74705SXin Li@end 196*67e74705SXin Li</pre> 197*67e74705SXin Li 198*67e74705SXin Li<p>Running <tt>scan-build</tt> on this source file produces the following output:</p> 199*67e74705SXin Li 200*67e74705SXin Li<img src="images/example_ns_returns_retained.png" alt="example returns retained"> 201*67e74705SXin Li 202*67e74705SXin Li<h4 id="attr_ns_returns_not_retained">Attribute 'ns_returns_not_retained' 203*67e74705SXin Li(Clang-specific)</h4> 204*67e74705SXin Li 205*67e74705SXin Li<p>The 'ns_returns_not_retained' attribute is the complement of '<a 206*67e74705SXin Lihref="#attr_ns_returns_retained">ns_returns_retained</a>'. Where a function or 207*67e74705SXin Limethod may appear to obey the Cocoa conventions and return a retained Cocoa 208*67e74705SXin Liobject, this attribute can be used to indicate that the object reference 209*67e74705SXin Lireturned should not be considered as an "owning" reference being 210*67e74705SXin Lireturned to the caller. The Foundation framework defines a 211*67e74705SXin Limacro <b><tt>NS_RETURNS_NOT_RETAINED</tt></b> that is functionally equivalent to 212*67e74705SXin Lithe one shown below.</p> 213*67e74705SXin Li 214*67e74705SXin Li<p>Usage is identical to <a 215*67e74705SXin Lihref="#attr_ns_returns_retained">ns_returns_retained</a>. When using the 216*67e74705SXin Liattribute, be sure to declare it within the proper macro that checks for 217*67e74705SXin Liits availability, as it is not available in earlier versions of the analyzer:</p> 218*67e74705SXin Li 219*67e74705SXin Li<pre class="code_example"> 220*67e74705SXin Li<span class="command">$ cat test.m</span> 221*67e74705SXin Li#ifndef __has_feature // Optional. 222*67e74705SXin Li#define __has_feature(x) 0 // Compatibility with non-clang compilers. 223*67e74705SXin Li#endif 224*67e74705SXin Li 225*67e74705SXin Li#ifndef NS_RETURNS_NOT_RETAINED 226*67e74705SXin Li#if __has_feature(attribute_ns_returns_not_retained) 227*67e74705SXin Li<span class="code_highlight">#define NS_RETURNS_NOT_RETAINED __attribute__((ns_returns_not_retained))</span> 228*67e74705SXin Li#else 229*67e74705SXin Li#define NS_RETURNS_NOT_RETAINED 230*67e74705SXin Li#endif 231*67e74705SXin Li#endif 232*67e74705SXin Li</pre> 233*67e74705SXin Li 234*67e74705SXin Li<h4 id="attr_cf_returns_retained">Attribute 'cf_returns_retained' 235*67e74705SXin Li(Clang-specific)</h4> 236*67e74705SXin Li 237*67e74705SXin Li<p>The GCC-style (Clang-specific) attribute 'cf_returns_retained' allows one to 238*67e74705SXin Liannotate an Objective-C method or C function as returning a retained Core 239*67e74705SXin LiFoundation object that the caller is responsible for releasing. The 240*67e74705SXin LiCoreFoundation framework defines a macro <b><tt>CF_RETURNS_RETAINED</tt></b> 241*67e74705SXin Lithat is functionally equivalent to the one shown below.</p> 242*67e74705SXin Li 243*67e74705SXin Li<p><b>Placing on Objective-C methods</b>: With respect to Objective-C methods., 244*67e74705SXin Lithis attribute is identical in its behavior and usage to 'ns_returns_retained' 245*67e74705SXin Liexcept for the distinction of returning a Core Foundation object instead of a 246*67e74705SXin LiCocoa object. This distinction is important for two reasons:</p> 247*67e74705SXin Li 248*67e74705SXin Li<ul> 249*67e74705SXin Li <li>Core Foundation objects are not automatically managed by the Objective-C 250*67e74705SXin Li garbage collector.</li> 251*67e74705SXin Li <li>Because Core Foundation is a C API, the analyzer cannot always tell that a 252*67e74705SXin Li pointer return value refers to a Core Foundation object. In contrast, it is 253*67e74705SXin Li trivial for the analyzer to recognize if a pointer refers to a Cocoa object 254*67e74705SXin Li (given the Objective-C type system). 255*67e74705SXin Li</ul> 256*67e74705SXin Li 257*67e74705SXin Li<p><b>Placing on C functions</b>: When placing the attribute 258*67e74705SXin Li'cf_returns_retained' on the declarations of C functions, the analyzer 259*67e74705SXin Liinterprets the function as:</p> 260*67e74705SXin Li 261*67e74705SXin Li<ol> 262*67e74705SXin Li <li>Returning a Core Foundation Object</li> 263*67e74705SXin Li <li>Treating the function as if it its name 264*67e74705SXin Licontained the keywords "create" or "copy". This means the 265*67e74705SXin Lireturned object as a +1 retain count that must be released by the caller, either 266*67e74705SXin Liby sending a <tt>release</tt> message (via toll-free bridging to an Objective-C 267*67e74705SXin Liobject pointer), calling <tt>CFRelease</tt> (or similar function), or using 268*67e74705SXin Li<tt>CFMakeCollectable</tt> to register the object with the Objective-C garbage 269*67e74705SXin Licollector.</li> 270*67e74705SXin Li</ol> 271*67e74705SXin Li 272*67e74705SXin Li<p><b>Example</b></p> 273*67e74705SXin Li 274*67e74705SXin Li<p>In this example, observe the difference in output when the code is compiled 275*67e74705SXin Lito not use garbage collection versus when it is compiled to only use garbage 276*67e74705SXin Licollection (<tt>-fobjc-gc-only</tt>).</p> 277*67e74705SXin Li 278*67e74705SXin Li<pre class="code_example"> 279*67e74705SXin Li<span class="command">$ cat test.m</span> 280*67e74705SXin Li$ cat test.m 281*67e74705SXin Li#import <Cocoa/Cocoa.h> 282*67e74705SXin Li 283*67e74705SXin Li#ifndef __has_feature // Optional. 284*67e74705SXin Li#define __has_feature(x) 0 // Compatibility with non-clang compilers. 285*67e74705SXin Li#endif 286*67e74705SXin Li 287*67e74705SXin Li#ifndef CF_RETURNS_RETAINED 288*67e74705SXin Li#if __has_feature(attribute_cf_returns_retained) 289*67e74705SXin Li<span class="code_highlight">#define CF_RETURNS_RETAINED __attribute__((cf_returns_retained))</span> 290*67e74705SXin Li#else 291*67e74705SXin Li#define CF_RETURNS_RETAINED 292*67e74705SXin Li#endif 293*67e74705SXin Li#endif 294*67e74705SXin Li 295*67e74705SXin Li@interface MyClass : NSObject {} 296*67e74705SXin Li- (NSDate*) returnsCFRetained <span class="code_highlight">CF_RETURNS_RETAINED</span>; 297*67e74705SXin Li- (NSDate*) alsoReturnsRetained; 298*67e74705SXin Li- (NSDate*) returnsNSRetained <span class="code_highlight">NS_RETURNS_RETAINED</span>; 299*67e74705SXin Li@end 300*67e74705SXin Li 301*67e74705SXin Li<span class="code_highlight">CF_RETURNS_RETAINED</span> 302*67e74705SXin LiCFDateRef returnsRetainedCFDate() { 303*67e74705SXin Li return CFDateCreate(0, CFAbsoluteTimeGetCurrent()); 304*67e74705SXin Li} 305*67e74705SXin Li 306*67e74705SXin Li@implementation MyClass 307*67e74705SXin Li- (NSDate*) returnsCFRetained { 308*67e74705SXin Li return (NSDate*) returnsRetainedCFDate(); <b><i>// No leak.</i></b> 309*67e74705SXin Li} 310*67e74705SXin Li 311*67e74705SXin Li- (NSDate*) alsoReturnsRetained { 312*67e74705SXin Li return (NSDate*) returnsRetainedCFDate(); <b><i>// Always report a leak.</i></b> 313*67e74705SXin Li} 314*67e74705SXin Li 315*67e74705SXin Li- (NSDate*) returnsNSRetained { 316*67e74705SXin Li return (NSDate*) returnsRetainedCFDate(); <b><i>// Report a leak when using GC.</i></b> 317*67e74705SXin Li} 318*67e74705SXin Li@end 319*67e74705SXin Li</pre> 320*67e74705SXin Li 321*67e74705SXin Li<p>Running <tt>scan-build</tt> on this example produces the following output:</p> 322*67e74705SXin Li 323*67e74705SXin Li<img src="images/example_cf_returns_retained.png" alt="example returns retained"> 324*67e74705SXin Li 325*67e74705SXin Li<p>When the above code is compiled using Objective-C garbage collection (i.e., 326*67e74705SXin Licode is compiled with the flag <tt>-fobjc-gc</tt> or <tt>-fobjc-gc-only</tt>), 327*67e74705SXin Li<tt>scan-build</tt> produces both the above error (with slightly different text 328*67e74705SXin Lito indicate the code uses garbage collection) as well as the following warning, 329*67e74705SXin Liwhich indicates a leak that occurs <em>only</em> when using garbage 330*67e74705SXin Licollection:</p> 331*67e74705SXin Li 332*67e74705SXin Li<img src="images/example_cf_returns_retained_gc.png" alt="example returns retained gc"> 333*67e74705SXin Li 334*67e74705SXin Li<h4 id="attr_cf_returns_not_retained">Attribute 'cf_returns_not_retained' 335*67e74705SXin Li(Clang-specific)</h4> 336*67e74705SXin Li 337*67e74705SXin Li<p>The 'cf_returns_not_retained' attribute is the complement of '<a 338*67e74705SXin Lihref="#attr_cf_returns_retained">cf_returns_retained</a>'. Where a function or 339*67e74705SXin Limethod may appear to obey the Core Foundation or Cocoa conventions and return 340*67e74705SXin Lia retained Core Foundation object, this attribute can be used to indicate that 341*67e74705SXin Lithe object reference returned should not be considered as an 342*67e74705SXin Li"owning" reference being returned to the caller. The 343*67e74705SXin LiCoreFoundation framework defines a macro <b><tt>CF_RETURNS_NOT_RETAINED</tt></b> 344*67e74705SXin Lithat is functionally equivalent to the one shown below.</p> 345*67e74705SXin Li 346*67e74705SXin Li<p>Usage is identical to <a 347*67e74705SXin Lihref="#attr_cf_returns_retained">cf_returns_retained</a>. When using the 348*67e74705SXin Liattribute, be sure to declare it within the proper macro that checks for 349*67e74705SXin Liits availability, as it is not available in earlier versions of the analyzer:</p> 350*67e74705SXin Li 351*67e74705SXin Li<pre class="code_example"> 352*67e74705SXin Li<span class="command">$ cat test.m</span> 353*67e74705SXin Li#ifndef __has_feature // Optional. 354*67e74705SXin Li#define __has_feature(x) 0 // Compatibility with non-clang compilers. 355*67e74705SXin Li#endif 356*67e74705SXin Li 357*67e74705SXin Li#ifndef CF_RETURNS_NOT_RETAINED 358*67e74705SXin Li#if __has_feature(attribute_cf_returns_not_retained) 359*67e74705SXin Li<span class="code_highlight">#define CF_RETURNS_NOT_RETAINED __attribute__((cf_returns_not_retained))</span> 360*67e74705SXin Li#else 361*67e74705SXin Li#define CF_RETURNS_NOT_RETAINED 362*67e74705SXin Li#endif 363*67e74705SXin Li#endif 364*67e74705SXin Li</pre> 365*67e74705SXin Li 366*67e74705SXin Li<h4 id="attr_ns_consumed">Attribute 'ns_consumed' 367*67e74705SXin Li(Clang-specific)</h4> 368*67e74705SXin Li 369*67e74705SXin Li<p>The 'ns_consumed' attribute can be placed on a specific parameter in either 370*67e74705SXin Lithe declaration of a function or an Objective-C method. It indicates to the 371*67e74705SXin Listatic analyzer that a <tt>release</tt> message is implicitly sent to the 372*67e74705SXin Liparameter upon completion of the call to the given function or method. The 373*67e74705SXin LiFoundation framework defines a macro <b><tt>NS_RELEASES_ARGUMENT</tt></b> that 374*67e74705SXin Liis functionally equivalent to the <tt>NS_CONSUMED</tt> macro shown below.</p> 375*67e74705SXin Li 376*67e74705SXin Li<p><b>Important note when using Garbage Collection</b>: Note that the analyzer 377*67e74705SXin Liessentially ignores this attribute when code is compiled to use Objective-C 378*67e74705SXin Ligarbage collection. This is because the <tt>release</tt> message does nothing 379*67e74705SXin Liwhen using GC. If the underlying function/method uses something like 380*67e74705SXin Li<tt>CFRelease</tt> to decrement the reference count, consider using 381*67e74705SXin Lithe <a href="#attr_cf_consumed">cf_consumed</a> attribute instead.</p> 382*67e74705SXin Li 383*67e74705SXin Li<p><b>Example</b></p> 384*67e74705SXin Li 385*67e74705SXin Li<pre class="code_example"> 386*67e74705SXin Li<span class="command">$ cat test.m</span> 387*67e74705SXin Li#ifndef __has_feature // Optional. 388*67e74705SXin Li#define __has_feature(x) 0 // Compatibility with non-clang compilers. 389*67e74705SXin Li#endif 390*67e74705SXin Li 391*67e74705SXin Li#ifndef NS_CONSUMED 392*67e74705SXin Li#if __has_feature(attribute_ns_consumed) 393*67e74705SXin Li<span class="code_highlight">#define NS_CONSUMED __attribute__((ns_consumed))</span> 394*67e74705SXin Li#else 395*67e74705SXin Li#define NS_CONSUMED 396*67e74705SXin Li#endif 397*67e74705SXin Li#endif 398*67e74705SXin Li 399*67e74705SXin Livoid consume_ns(id <span class="code_highlight">NS_CONSUMED</span> x); 400*67e74705SXin Li 401*67e74705SXin Livoid test() { 402*67e74705SXin Li id x = [[NSObject alloc] init]; 403*67e74705SXin Li consume_ns(x); <b><i>// No leak!</i></b> 404*67e74705SXin Li} 405*67e74705SXin Li 406*67e74705SXin Li@interface Foo : NSObject 407*67e74705SXin Li+ (void) releaseArg:(id) <span class="code_highlight">NS_CONSUMED</span> x; 408*67e74705SXin Li+ (void) releaseSecondArg:(id)x second:(id) <span class="code_highlight">NS_CONSUMED</span> y; 409*67e74705SXin Li@end 410*67e74705SXin Li 411*67e74705SXin Livoid test_method() { 412*67e74705SXin Li id x = [[NSObject alloc] init]; 413*67e74705SXin Li [Foo releaseArg:x]; <b><i>// No leak!</i></b> 414*67e74705SXin Li} 415*67e74705SXin Li 416*67e74705SXin Livoid test_method2() { 417*67e74705SXin Li id a = [[NSObject alloc] init]; 418*67e74705SXin Li id b = [[NSObject alloc] init]; 419*67e74705SXin Li [Foo releaseSecondArg:a second:b]; <b><i>// 'a' is leaked, but 'b' is released.</i></b> 420*67e74705SXin Li} 421*67e74705SXin Li</pre> 422*67e74705SXin Li 423*67e74705SXin Li<h4 id="attr_cf_consumed">Attribute 'cf_consumed' 424*67e74705SXin Li(Clang-specific)</h4> 425*67e74705SXin Li 426*67e74705SXin Li<p>The 'cf_consumed' attribute is practically identical to <a 427*67e74705SXin Lihref="#attr_ns_consumed">ns_consumed</a>. The attribute can be placed on a 428*67e74705SXin Lispecific parameter in either the declaration of a function or an Objective-C 429*67e74705SXin Limethod. It indicates to the static analyzer that the object reference is 430*67e74705SXin Liimplicitly passed to a call to <tt>CFRelease</tt> upon completion of the call 431*67e74705SXin Lito the given function or method. The CoreFoundation framework defines a macro 432*67e74705SXin Li<b><tt>CF_RELEASES_ARGUMENT</tt></b> that is functionally equivalent to the 433*67e74705SXin Li<tt>CF_CONSUMED</tt> macro shown below.</p> 434*67e74705SXin Li 435*67e74705SXin Li<p>Operationally this attribute is nearly identical to 'ns_consumed' with the 436*67e74705SXin Limain difference that the reference count decrement still occurs when using 437*67e74705SXin LiObjective-C garbage collection (which is import for Core Foundation types, 438*67e74705SXin Liwhich are not automatically garbage collected).</p> 439*67e74705SXin Li 440*67e74705SXin Li<p><b>Example</b></p> 441*67e74705SXin Li 442*67e74705SXin Li<pre class="code_example"> 443*67e74705SXin Li<span class="command">$ cat test.m</span> 444*67e74705SXin Li#ifndef __has_feature // Optional. 445*67e74705SXin Li#define __has_feature(x) 0 // Compatibility with non-clang compilers. 446*67e74705SXin Li#endif 447*67e74705SXin Li 448*67e74705SXin Li#ifndef CF_CONSUMED 449*67e74705SXin Li#if __has_feature(attribute_cf_consumed) 450*67e74705SXin Li<span class="code_highlight">#define CF_CONSUMED __attribute__((cf_consumed))</span> 451*67e74705SXin Li#else 452*67e74705SXin Li#define CF_CONSUMED 453*67e74705SXin Li#endif 454*67e74705SXin Li#endif 455*67e74705SXin Li 456*67e74705SXin Livoid consume_cf(id <span class="code_highlight">CF_CONSUMED</span> x); 457*67e74705SXin Livoid consume_CFDate(CFDateRef <span class="code_highlight">CF_CONSUMED</span> x); 458*67e74705SXin Li 459*67e74705SXin Livoid test() { 460*67e74705SXin Li id x = [[NSObject alloc] init]; 461*67e74705SXin Li consume_cf(x); <b><i>// No leak!</i></b> 462*67e74705SXin Li} 463*67e74705SXin Li 464*67e74705SXin Livoid test2() { 465*67e74705SXin Li CFDateRef date = CFDateCreate(0, CFAbsoluteTimeGetCurrent()); 466*67e74705SXin Li consume_CFDate(date); <b><i>// No leak, including under GC!</i></b> 467*67e74705SXin Li 468*67e74705SXin Li} 469*67e74705SXin Li 470*67e74705SXin Li@interface Foo : NSObject 471*67e74705SXin Li+ (void) releaseArg:(CFDateRef) <span class="code_highlight">CF_CONSUMED</span> x; 472*67e74705SXin Li@end 473*67e74705SXin Li 474*67e74705SXin Livoid test_method() { 475*67e74705SXin Li CFDateRef date = CFDateCreate(0, CFAbsoluteTimeGetCurrent()); 476*67e74705SXin Li [Foo releaseArg:date]; <b><i>// No leak!</i></b> 477*67e74705SXin Li} 478*67e74705SXin Li</pre> 479*67e74705SXin Li 480*67e74705SXin Li<h4 id="attr_ns_consumes_self">Attribute 'ns_consumes_self' 481*67e74705SXin Li(Clang-specific)</h4> 482*67e74705SXin Li 483*67e74705SXin Li<p>The 'ns_consumes_self' attribute can be placed only on an Objective-C method 484*67e74705SXin Lideclaration. It indicates that the receiver of the message is 485*67e74705SXin Li"consumed" (a single reference count decremented) after the message 486*67e74705SXin Liis sent. This matches the semantics of all "init" methods.</p> 487*67e74705SXin Li 488*67e74705SXin Li<p>One use of this attribute is declare your own init-like methods that do not 489*67e74705SXin Lifollow the standard Cocoa naming conventions.</p> 490*67e74705SXin Li 491*67e74705SXin Li<p><b>Example</b></p> 492*67e74705SXin Li 493*67e74705SXin Li<pre class="code_example"> 494*67e74705SXin Li#ifndef __has_feature 495*67e74705SXin Li#define __has_feature(x) 0 // Compatibility with non-clang compilers. 496*67e74705SXin Li#endif 497*67e74705SXin Li 498*67e74705SXin Li#ifndef NS_CONSUMES_SELF 499*67e74705SXin Li#if __has_feature((attribute_ns_consumes_self)) 500*67e74705SXin Li<span class="code_highlight">#define NS_CONSUMES_SELF __attribute__((ns_consumes_self))</span> 501*67e74705SXin Li#else 502*67e74705SXin Li#define NS_CONSUMES_SELF 503*67e74705SXin Li#endif 504*67e74705SXin Li#endif 505*67e74705SXin Li 506*67e74705SXin Li@interface MyClass : NSObject 507*67e74705SXin Li- initWith:(MyClass *)x; 508*67e74705SXin Li- nonstandardInitWith:(MyClass *)x <span class="code_highlight">NS_CONSUMES_SELF</span> NS_RETURNS_RETAINED; 509*67e74705SXin Li@end 510*67e74705SXin Li</pre> 511*67e74705SXin Li 512*67e74705SXin Li<p>In this example, <tt>-nonstandardInitWith:</tt> has the same ownership 513*67e74705SXin Lisemantics as the init method <tt>-initWith:</tt>. The static analyzer will 514*67e74705SXin Liobserve that the method consumes the receiver, and then returns an object with 515*67e74705SXin Lia +1 retain count.</p> 516*67e74705SXin Li 517*67e74705SXin Li<p>The Foundation framework defines a macro <b><tt>NS_REPLACES_RECEIVER</tt></b> 518*67e74705SXin Liwhich is functionally equivalent to the combination of <tt>NS_CONSUMES_SELF</tt> 519*67e74705SXin Liand <tt>NS_RETURNS_RETAINED</tt> shown above.</p> 520*67e74705SXin Li 521*67e74705SXin Li 522*67e74705SXin Li<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> 523*67e74705SXin Li<h2 id="custom_assertions">Custom Assertion Handlers</h2> 524*67e74705SXin Li<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> 525*67e74705SXin Li 526*67e74705SXin Li<p>The analyzer exploits code assertions by pruning off paths where the 527*67e74705SXin Liassertion condition is false. The idea is capture any program invariants 528*67e74705SXin Lispecified in the assertion that the developer may know but is not immediately 529*67e74705SXin Liapparent in the code itself. In this way assertions make implicit assumptions 530*67e74705SXin Liexplicit in the code, which not only makes the analyzer more accurate when 531*67e74705SXin Lifinding bugs, but can help others better able to understand your code as well. 532*67e74705SXin LiIt can also help remove certain kinds of analyzer false positives by pruning off 533*67e74705SXin Lifalse paths.</p> 534*67e74705SXin Li 535*67e74705SXin Li<p>In order to exploit assertions, however, the analyzer must understand when it 536*67e74705SXin Liencounters an "assertion handler." Typically assertions are 537*67e74705SXin Liimplemented with a macro, with the macro performing a check for the assertion 538*67e74705SXin Licondition and, when the check fails, calling an assertion handler. For example, consider the following code 539*67e74705SXin Lifragment:</p> 540*67e74705SXin Li 541*67e74705SXin Li<pre class="code_example"> 542*67e74705SXin Livoid foo(int *p) { 543*67e74705SXin Li assert(p != NULL); 544*67e74705SXin Li} 545*67e74705SXin Li</pre> 546*67e74705SXin Li 547*67e74705SXin Li<p>When this code is preprocessed on Mac OS X it expands to the following:</p> 548*67e74705SXin Li 549*67e74705SXin Li<pre class="code_example"> 550*67e74705SXin Livoid foo(int *p) { 551*67e74705SXin Li (__builtin_expect(!(p != NULL), 0) ? __assert_rtn(__func__, "t.c", 4, "p != NULL") : (void)0); 552*67e74705SXin Li} 553*67e74705SXin Li</pre> 554*67e74705SXin Li 555*67e74705SXin Li<p>In this example, the assertion handler is <tt>__assert_rtn</tt>. When called, 556*67e74705SXin Limost assertion handlers typically print an error and terminate the program. The 557*67e74705SXin Lianalyzer can exploit such semantics by ending the analysis of a path once it 558*67e74705SXin Lihits a call to an assertion handler.</p> 559*67e74705SXin Li 560*67e74705SXin Li<p>The trick, however, is that the analyzer needs to know that a called function 561*67e74705SXin Liis an assertion handler; otherwise the analyzer might assume the function call 562*67e74705SXin Lireturns and it will continue analyzing the path where the assertion condition 563*67e74705SXin Lifailed. This can lead to false positives, as the assertion condition usually 564*67e74705SXin Liimplies a safety condition (e.g., a pointer is not null) prior to performing 565*67e74705SXin Lisome action that depends on that condition (e.g., dereferencing a pointer).</p> 566*67e74705SXin Li 567*67e74705SXin Li<p>The analyzer knows about several well-known assertion handlers, but can 568*67e74705SXin Liautomatically infer if a function should be treated as an assertion handler if 569*67e74705SXin Liit is annotated with the 'noreturn' attribute or the (Clang-specific) 570*67e74705SXin Li'analyzer_noreturn' attribute. Note that, currently, clang does not support 571*67e74705SXin Lithese attributes on Objective-C methods and C++ methods.</p> 572*67e74705SXin Li 573*67e74705SXin Li<h4 id="attr_noreturn">Attribute 'noreturn'</h4> 574*67e74705SXin Li 575*67e74705SXin Li<p>The 'noreturn' attribute is a GCC-attribute that can be placed on the 576*67e74705SXin Lideclarations of functions. It means exactly what its name implies: a function 577*67e74705SXin Liwith a 'noreturn' attribute should never return.</p> 578*67e74705SXin Li 579*67e74705SXin Li<p>Specific details of the syntax of using the 'noreturn' attribute can be found 580*67e74705SXin Liin <a 581*67e74705SXin Lihref="http://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html#index-g_t_0040code_007bnoreturn_007d-function-attribute-2264">GCC's 582*67e74705SXin Lidocumentation</a>.</p> 583*67e74705SXin Li 584*67e74705SXin Li<p>Not only does the analyzer exploit this information when pruning false paths, 585*67e74705SXin Libut the compiler also takes it seriously and will generate different code (and 586*67e74705SXin Lipossibly better optimized) under the assumption that the function does not 587*67e74705SXin Lireturn.</p> 588*67e74705SXin Li 589*67e74705SXin Li<p><b>Example</b></p> 590*67e74705SXin Li 591*67e74705SXin Li<p>On Mac OS X, the function prototype for <tt>__assert_rtn</tt> (declared in 592*67e74705SXin Li<tt>assert.h</tt>) is specifically annotated with the 'noreturn' attribute:</p> 593*67e74705SXin Li 594*67e74705SXin Li<pre class="code_example"> 595*67e74705SXin Livoid __assert_rtn(const char *, const char *, int, const char *) <span class="code_highlight">__attribute__((__noreturn__))</span>; 596*67e74705SXin Li</pre> 597*67e74705SXin Li 598*67e74705SXin Li<h4 id="attr_analyzer_noreturn">Attribute 'analyzer_noreturn' (Clang-specific)</h4> 599*67e74705SXin Li 600*67e74705SXin Li<p>The Clang-specific 'analyzer_noreturn' attribute is almost identical to 601*67e74705SXin Li'noreturn' except that it is ignored by the compiler for the purposes of code 602*67e74705SXin Ligeneration.</p> 603*67e74705SXin Li 604*67e74705SXin Li<p>This attribute is useful for annotating assertion handlers that actually 605*67e74705SXin Li<em>can</em> return, but for the purpose of using the analyzer we want to 606*67e74705SXin Lipretend that such functions do not return.</p> 607*67e74705SXin Li 608*67e74705SXin Li<p>Because this attribute is Clang-specific, its use should be conditioned with 609*67e74705SXin Lithe use of preprocessor macros.</p> 610*67e74705SXin Li 611*67e74705SXin Li<p><b>Example</b> 612*67e74705SXin Li 613*67e74705SXin Li<pre class="code_example"> 614*67e74705SXin Li#ifndef CLANG_ANALYZER_NORETURN 615*67e74705SXin Li#if __has_feature(attribute_analyzer_noreturn) 616*67e74705SXin Li<span class="code_highlight">#define CLANG_ANALYZER_NORETURN __attribute__((analyzer_noreturn))</span> 617*67e74705SXin Li#else 618*67e74705SXin Li#define CLANG_ANALYZER_NORETURN 619*67e74705SXin Li#endif 620*67e74705SXin Li#endif 621*67e74705SXin Li 622*67e74705SXin Livoid my_assert_rtn(const char *, const char *, int, const char *) <span class="code_highlight">CLANG_ANALYZER_NORETURN</span>; 623*67e74705SXin Li</pre> 624*67e74705SXin Li 625*67e74705SXin Li</div> 626*67e74705SXin Li</div> 627*67e74705SXin Li</body> 628*67e74705SXin Li</html> 629*67e74705SXin Li 630
