annotations.html revision 5303644db49c7f20d269c6d0da314cab1c887b3c
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" 2 "http://www.w3.org/TR/html4/strict.dtd"> 3<html> 4<head> 5 <title>Source Annotations</title> 6 <link type="text/css" rel="stylesheet" href="menu.css" /> 7 <link type="text/css" rel="stylesheet" href="content.css" /> 8</head> 9<body> 10 11<!--#include virtual="menu.html.incl"--> 12 13<div id="content"> 14 15<h1>Source Annotations</h1> 16 17<p>The Clang frontend supports several source-level annotations in the form of 18<a href="http://gcc.gnu.org/onlinedocs/gcc/Attribute-Syntax.html">GCC-style 19attributes</a> and pragmas that can help make using the Clang Static Analyzer 20more useful. These annotations can both help suppress false positives as well as 21enhance the analyzer's ability to find bugs.</p> 22 23<p>This page gives a practical overview of such annotations. For more technical 24specifics regarding Clang-specific annotations please see the Clang's list of <a 25href="http://clang.llvm.org/docs/LanguageExtensions.html">language 26extensions</a>. Details of "standard" GCC attributes (that Clang also 27supports) can be found in the <a href="http://gcc.gnu.org/onlinedocs/gcc/">GCC 28manual</a>, with the majority of the relevant attributes being in the section on 29<a href="http://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html">function 30attributes</a>.</p> 31 32<p>Note that attributes that are labeled <b>Clang-specific</b> are not 33recognized by GCC. Their use can be conditioned using preprocessor macros 34(examples included on this page).</p> 35 36<ul> 37<li><a href="#generic">Annotations to Enhance Generic Checks</a></li> 38 <ul> 39 <li><a href="#null_checking">Null Pointer Checking</a></li> 40 <ul> 41 <li><a href="#attr_nonnull">Attribute 'nonnull'</a></li> 42 </ul> 43 </ul> 44<li><a href="#macosx">Mac OS X API Annotations</a></li> 45 <ul> 46 <li><a href="#cocoa_mem">Cocoa & Core Foundation Memory Management 47 Annotations</a></li> 48 <ul> 49 <li><a href="#attr_ns_returns_retained">Attribute 50 'ns_returns_retained'</a></li> 51 <li><a href="#attr_cf_returns_retained">Attribute 52 'cf_returns_retained'</a></li> 53 </ul> 54 </ul> 55<li><a href="#custom_assertions">Custom Assertion Handlers</a></li> 56 <ul> 57 <li><a href="#attr_noreturn">Attribute 'noreturn'</a></li> 58 <li><a href="#attr_analyzer_noreturn">Attribute 'analyzer_noreturn'</a></li> 59 </ul> 60</ul> 61 62<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> 63<h2 id="generic">Annotations to Enhance Generic Checks</h2> 64<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> 65 66<h3 id="null_checking">Null Pointer Checking</h3> 67 68<h4 id="attr_nonnull">Attribute 'nonnull'</h4> 69 70<p>The analyzer recognizes the GCC attribute 'nonnull', which indicates that a 71function expects that a given function parameter is not a null pointer. Specific 72details of the syntax of using the 'nonnull' attribute can be found in <a 73href="http://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html#index-g_t_0040code_007bnonnull_007d-function-attribute-2263">GCC's 74documentation</a>.</p> 75 76<p>Both the Clang compiler and GCC will flag warnings for simple cases where a 77null pointer is directly being passed to a function with a 'nonnull' parameter 78(e.g., as a constant). The analyzer extends this checking by using its deeper 79symbolic analysis to track what pointer values are potentially null and then 80flag warnings when they are passed in a function call via a 'nonnull' 81parameter.</p> 82 83<p><b>Example</b></p> 84 85<pre class="code_example"> 86<span class="command">$ cat test.m</span> 87int bar(int*p, int q, int *r) __attribute__((nonnull(1,3))); 88 89int foo(int *p, int *q) { 90 return !p ? bar(q, 2, p) 91 : bar(p, 2, q); 92} 93</pre> 94 95<p>Running <tt>scan-build</tt> over this source produces the following 96output:</p> 97 98<img src="images/xample_attribute_nonnull.png"> 99 100<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> 101<h2 id="macosx">Mac OS X API Annotations</h2> 102<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> 103 104<h3 id="cocoa_mem">Cocoa & Core Foundation Memory Management 105Annotations</h3> 106 107<!-- 108<p>As described in <a href="/available_checks.html#retain_release">Available 109Checks</a>, 110--> 111<p>The analyzer supports the proper management of retain counts for 112both Cocoa and Core Foundation objects. This checking is largely based on 113enforcing Cocoa and Core Foundation naming conventions for Objective-C methods 114(Cocoa) and C functions (Core Foundation). Not strictly following these 115conventions can cause the analyzer to miss bugs or flag false positives.</p> 116 117<p>One can educate the analyzer (and others who read your code) about methods or 118functions that deviate from the Cocoa and Core Foundation conventions using the 119attributes described here.</p> 120 121<h4 id="attr_ns_returns_retained">Attribute 'ns_returns_retained' 122(Clang-specific)</h4> 123 124<p>The GCC-style (Clang-specific) attribute 'ns_returns_retained' allows one to 125annotate an Objective-C method or C function as returning a retained Cocoa 126object that the caller is responsible for releasing (via sending a 127<tt>release</tt> message to the object).</p> 128 129<p><b>Placing on Objective-C methods</b>: For Objective-C methods, this 130annotation essentially tells the analyzer to treat the method as if its name 131begins with "alloc" or "new" or contais the word 132"copy".</p> 133 134<p><b>Placing on C functions</b>: For C functions returning Cocoa objects, the 135analyzer typically does not make any assumptions about whether or not the object 136is returned retained. Explicitly adding the 'ns_returns_retained' attribute to C 137functions allows the analyzer to perform extra checking.</p> 138 139<p><b>Important note when using Garbage Collection</b>: Note that the analyzer 140interprets this attribute slightly differently when using Objective-C garbage 141collection (available on Mac OS 10.5+). When analyzing Cocoa code that uses 142garbage collection, "alloc" methods are assumed to return an object 143that is managed by the garbage collector (and thus doesn't have a retain count 144the caller must balance). These same assumptions are applied to methods or 145functions annotated with 'ns_returns_retained'. If you are returning a Core 146Foundation object (which may not be managed by the garbage collector) you should 147use 'cf_returns_retained'.</p> 148 149<p><b>Example</b></p> 150 151<pre class="code_example"> 152<span class="command">$ cat test.m</span> 153#import <Foundation/Foundation.h> 154 155#ifndef NS_RETURNS_RETAINED 156#if __clang__ 157<span class="code_highlight">#define NS_RETURNS_RETAINED __attribute__((ns_returns_retained))</span> 158#else 159#define NS_RETURNS_RETAINED 160#endif 161#endif 162 163@interface MyClass : NSObject {} 164- (NSString*) returnsRetained <span class="code_highlight">NS_RETURNS_RETAINED</span>; 165- (NSString*) alsoReturnsRetained; 166@end 167 168@implementation MyClass 169- (NSString*) returnsRetained { 170 return [[NSString alloc] initWithCString:"no leak here"]; 171} 172- (NSString*) alsoReturnsRetained { 173 return [[NSString alloc] initWithCString:"flag a leak"]; 174} 175@end 176</pre> 177 178<p>Running <tt>scan-build</tt> on this source file produces the following output:</p> 179 180<img src="images/example_ns_returns_retained.png"> 181 182<h4 id="attr_cf_returns_retained">Attribute 'cf_returns_retained' 183(Clang-specific)</h4> 184 185<p>The GCC-style (Clang-specific) attribute 'cf_returns_retained' allows one to 186annotate an Objective-C method or C function as returning a retained Core 187Foundation object that the caller is responsible for releasing. 188 189<p><b>Placing on Objective-C methods</b>: With respect to Objective-C methods., 190this attribute is identical in its behavior and usage to 'ns_returns_retained' 191except for the distinction of returning a Core Foundation object instead of a 192Cocoa object. This distinction is important for two reasons:</p> 193 194<ul> 195 <li>Core Foundation objects are not automatically managed by the Objective-C 196 garbage collector.</li> 197 <li>Because Core Foundation is a C API, the analyzer cannot always tell that a 198 pointer return value refers to a Core Foundation object. In contrast, it is 199 trivial for the analyzer to recognize if a pointer refers to a Cocoa object 200 (given the Objective-C type system).</p> 201</ul> 202 203<p><b>Placing on C functions</b>: When placing the attribute 204'cf_returns_retained' on the declarations of C functions, the analyzer 205interprets the function as:</p> 206 207<ol> 208 <li>Returning a Core Foundation Object</li> 209 <li>Treating the function as if it its name 210contained the keywords "create" or "copy". This means the 211returned object as a +1 retain count that must be released by the caller, either 212by sending a <tt>release</tt> message (via toll-free bridging to an Objective-C 213object pointer), calling <tt>CFRelease</tt> (or similar function), or using 214<tt>CFMakeCollectable</tt> to register the object with the Objective-C garbage 215collector.</li> 216</ol> 217 218<p><b>Example</b></p> 219 220<p>In this example, observe the difference in output when the code is compiled 221to not use garbage collection versus when it is compiled to only use garbage 222collection (<tt>-fobjc-gc-only</tt>).</p> 223 224<pre class="code_example"> 225<span class="command">$ cat test.m</span> 226$ cat test.m 227#import <Cocoa/Cocoa.h> 228 229#ifndef CF_RETURNS_RETAINED 230#if __clang__ 231<span class="code_highlight">#define CF_RETURNS_RETAINED __attribute__((cf_returns_retained))</span> 232#else 233#define CF_RETURNS_RETAINED 234#endif 235#endif 236 237@interface MyClass : NSObject {} 238- (NSDate*) returnsCFRetained <span class="code_highlight">CF_RETURNS_RETAINED</span>; 239- (NSDate*) alsoReturnsRetained; 240- (NSDate*) returnsNSRetained <span class="code_highlight">NS_RETURNS_RETAINED</span>; 241@end 242 243<span class="code_highlight">CF_RETURNS_RETAINED</span> 244CFDateRef returnsRetainedCFDate() { 245 return CFDateCreate(0, CFAbsoluteTimeGetCurrent()); 246} 247 248@implementation MyClass 249- (NSDate*) returnsCFRetained { 250 return (NSDate*) returnsRetainedCFDate(); // No leak. 251} 252 253- (NSDate*) alsoReturnsRetained { 254 return (NSDate*) returnsRetainedCFDate(); // Always report a leak. 255} 256 257- (NSDate*) returnsNSRetained { 258 return (NSDate*) returnsRetainedCFDate(); // Report a leak when using GC. 259} 260@end 261</pre> 262 263<p>Running <tt>scan-build</tt> on this example produces the following output:</p> 264 265<img src="images/example_cf_returns_retained.png"> 266 267</p>When the above code is compiled using Objective-C garbage collection (i.e., 268code is compiled with the flag <tt>-fobjc-gc</tt> or <tt>-fobjc-gc-only</tt>), 269<tt>scan-build</tt> produces both the above error (with slightly different text 270to indicate the code uses garbage collection) as well as the following warning, 271which indicates a leak that occurs <em>only</em> when using garbage 272collection:</p> 273 274<img src="images/example_cf_returns_retained_gc.png"> 275 276<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> 277<h2 id="custom_assertions">Custom Assertion Handlers</h2> 278<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> 279 280<p>The analyzer exploits code assertions by pruning off paths where the 281assertion condition is false. The idea is capture any program invariants 282specified in the assertion that the developer may know but is not immediately 283apparent in the code itself. In this way assertions make implicit assumptions 284explicit in the code, which not only makes the analyzer more accurate when 285finding bugs, but can help others better able to understand your code as well. 286It can also help remove certain kinds of analyzer false positives by pruning off 287false paths.</p> 288 289<p>In order to exploit assertions, however, the analyzer must understand when it 290encounters an "assertion handler." Typically assertions are 291implemented with a macro, with the macro performing a check for the assertion 292condition and, when the check fails, calling an assertion handler. For example, consider the following code 293fragment:</p> 294 295<pre class="code_example"> 296void foo(int *p) { 297 assert(p != NULL); 298} 299</pre> 300 301<p>When this code is preprocessed on Mac OS X it expands to the following:</p> 302 303<pre class="code_example"> 304void foo(int *p) { 305 (__builtin_expect(!(p != NULL), 0) ? __assert_rtn(__func__, "t.c", 4, "p != NULL") : (void)0); 306} 307</pre> 308 309<p>In this example, the assertion handler is <tt>__assert_rtn</tt>. When called, 310most assertion handlers typically print an error and terminate the program. The 311analyzer can exploit such semantics by ending the analysis of a path once it 312hits a call to an assertion handler.</p> 313 314<p>The trick, however, is that the analyzer needs to know that a called function 315is an assertion handler; otherwise the analyzer might assume the function call 316returns and it will continue analyzing the path where the assertion condition 317failed. This can lead to false positives, as the assertion condition usually 318implies a safety condition (e.g., a pointer is not null) prior to performing 319some action that depends on that condition (e.g., dereferencing a pointer).</p> 320 321<p>The analyzer knows about several well-known assertion handlers, but can 322automatically infer if a function should be treated as an assertion handler if 323it is annotated with the 'noreturn' attribute or the (Clang-specific) 324'analyzer_noreturn' attribute.</p> 325 326<h4 id="attr_noreturn">Attribute 'noreturn'</h4> 327 328<p>The 'noreturn' attribute is a GCC-attribute that can be placed on the 329declarations of functions. It means exactly what its name implies: a function 330with a 'noreturn' attribute should never return.</p> 331 332<p>Specific details of the syntax of using the 'noreturn' attribute can be found 333in <a 334href="http://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html#index-g_t_0040code_007bnoreturn_007d-function-attribute-2264">GCC's 335documentation</a>.</p> 336 337<p>Not only does the analyzer exploit this information when pruning false paths, 338but the compiler also takes it seriously and will generate different code (and 339possibly better optimized) under the assumption that the function does not 340return.</p> 341 342<p><b>Example</b></p> 343 344<p>On Mac OS X, the function prototype for <tt>__assert_rtn</tt> (declared in 345<tt>assert.h</tt>) is specifically annotated with the 'noreturn' attribute:</p> 346 347<pre class="code_example"> 348void __assert_rtn(const char *, const char *, int, const char *) <span class="code_highlight">__attribute__((__noreturn__))</span>; 349</pre> 350 351<h4 id="attr_analyzer_noreturn">Attribute 'analyzer_noreturn' (Clang-specific)</h4> 352 353<p>The Clang-specific 'analyzer_noreturn' attribute is almost identical to 354'noreturn' except that it is ignored by the compiler for the purposes of code 355generation.</p> 356 357<p>This attribute is useful for annotating assertion handlers that actually 358<em>can</em> return, but for the purpose of using the analyzer we want to 359pretend that such functions do not return.</p> 360 361<p>Because this attribute is Clang-specific, its use should be conditioned with 362the use of preprocessor macros.</p> 363 364<p><b>Example</b> 365 366<pre class="code_example"> 367#ifndef CLANG_ANALYZER_NORETURN 368#if __clang__ 369<span class="code_highlight">#define CLANG_ANALYZER_NORETURN __attribute__((analyzer_noreturn))</span> 370#else 371#define CLANG_ANALYZER_NORETURN 372#endif 373 374void my_assert_rtn(const char *, const char *, int, const char *) <span class="code_highlight">CLANG_ANALYZER_NORETURN</span>; 375</pre> 376 377</div> 378</body> 379</html> 380 381