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