clang/www/analyzer/annotations.html

   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   <script type="text/javascript" src="scripts/menu.js"></script>
   9 </head>
  10 <body>
  11
  12 <div id="page">
  13 <!--#include virtual="menu.html.incl"-->
  14
  15 <div id="content">
  16
  17 <h1>Source Annotations</h1>
  18
  19 <p>The Clang frontend supports several source-level annotations in the form of
  20 <a href="https://gcc.gnu.org/onlinedocs/gcc/Attribute-Syntax.html">GCC-style
  21 attributes</a> and pragmas that can help make using the Clang Static Analyzer
  22 more useful. These annotations can both help suppress false positives as well as
  23 enhance the analyzer's ability to find bugs.</p>
  24
  25 <p>This page gives a practical overview of such annotations. For more technical
  26 specifics regarding Clang-specific annotations please see the Clang's list of <a
  27 href="https://clang.llvm.org/docs/LanguageExtensions.html">language
  28 extensions</a>. Details of &quot;standard&quot; GCC attributes (that Clang also
  29 supports) can be found in the <a href="https://gcc.gnu.org/onlinedocs/gcc/">GCC
  30 manual</a>, with the majority of the relevant attributes being in the section on
  31 <a href="https://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html">function
  32 attributes</a>.</p>
  33
  34 <p>Note that attributes that are labeled <b>Clang-specific</b> are not
  35 recognized by GCC. Their use can be conditioned using preprocessor macros
  36 (examples included on this page).</p>
  37
  38 <h4>Specific Topics</h4>
  39
  40 <ul>
  41 <li><a href="#generic">Annotations to Enhance Generic Checks</a>
  42   <ul>
  43     <li><a href="#null_checking"><span>Null Pointer Checking</span></a>
  44     <ul>
  45       <li><a href="#attr_nonnull"><span>Attribute 'nonnull'</span></a></li>
  46     </ul>
  47     </li>
  48   </ul>
  49 </li>
  50 <li><a href="#macosx">Mac OS X API Annotations</a>
  51   <ul>
  52     <li><a href="#cocoa_mem">Cocoa &amp; Core Foundation Memory Management Annotations</a>
  53     <ul>
  54       <li><a href="#attr_ns_returns_retained">Attribute 'ns_returns_retained'</a></li>
  55       <li><a href="#attr_ns_returns_not_retained">Attribute 'ns_returns_not_retained'</a></li>
  56       <li><a href="#attr_cf_returns_retained">Attribute 'cf_returns_retained'</a></li>
  57       <li><a href="#attr_cf_returns_not_retained">Attribute 'cf_returns_not_retained'</a></li>
  58       <li><a href="#attr_ns_consumed">Attribute 'ns_consumed'</a></li>
  59       <li><a href="#attr_cf_consumed">Attribute 'cf_consumed'</a></li>
  60       <li><a href="#attr_ns_consumes_self">Attribute 'ns_consumes_self'</a></li>
  61     </ul>
  62     </li>
  63     <li><a href="#osobject_mem">Libkern Memory Management Annotations</a>
  64       <ul>
  65         <li><a href="#attr_os_returns_retained">Attribute 'os_returns_retained'</a></li>
  66         <li><a href="#attr_os_returns_not_retained">Attribute 'os_returns_not_retained'</a></li>
  67         <li><a href="#attr_os_consumed">Attribute 'os_consumed'</a></li>
  68         <li><a href="#attr_os_consumes_this">Attribute 'os_consumes_this'</a></li>
  69         <li><a href="#os_out_parameters">Out Parameters</a></li>
  70       </ul>
  71
  72     </li>
  73   </ul>
  74 </li>
  75 <li><a href="#custom_assertions">Custom Assertion Handlers</a>
  76   <ul>
  77     <li><a href="#attr_noreturn">Attribute 'noreturn'</a></li>
  78     <li><a href="#attr_analyzer_noreturn">Attribute 'analyzer_noreturn'</a></li>
  79   </ul>
  80   </li>
  81 </ul>
  82
  83 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
  84 <h2 id="generic">Annotations to Enhance Generic Checks</h2>
  85 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
  86
  87 <h3 id="null_checking">Null Pointer Checking</h3>
  88
  89 <h4 id="attr_nonnull">Attribute 'nonnull'</h4>
  90
  91 <p>The analyzer recognizes the GCC attribute 'nonnull', which indicates that a
  92 function expects that a given function parameter is not a null pointer. Specific
  93 details of the syntax of using the 'nonnull' attribute can be found in <a
  94 href="https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-nonnull-function-attribute">GCC's
  95 documentation</a>.</p>
  96
  97 <p>Both the Clang compiler and GCC will flag warnings for simple cases where a
  98 null pointer is directly being passed to a function with a 'nonnull' parameter
  99 (e.g., as a constant). The analyzer extends this checking by using its deeper
 100 symbolic analysis to track what pointer values are potentially null and then
 101 flag warnings when they are passed in a function call via a 'nonnull'
 102 parameter.</p>
 103
 104 <p><b>Example</b></p>
 105
 106 <pre class="code_example">
 107 <span class="command">$ cat test.m</span>
 108 int bar(int*p, int q, int *r) __attribute__((nonnull(1,3)));
 109
 110 int foo(int *p, int *q) {
 111    return !p ? bar(q, 2, p)
 112              : bar(p, 2, q);
 113 }
 114 </pre>
 115
 116 <p>Running <tt>scan-build</tt> over this source produces the following
 117 output:</p>
 118
 119 <img src="images/example_attribute_nonnull.png" alt="example attribute nonnull">
 120
 121 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
 122 <h2 id="macosx">Mac OS X API Annotations</h2>
 123 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
 124
 125 <h3 id="cocoa_mem">Cocoa &amp; Core Foundation Memory Management
 126 Annotations</h3>
 127
 128 <!--
 129 <p>As described in <a href="/available_checks.html#retain_release">Available
 130 Checks</a>,
 131 -->
 132 <p>The analyzer supports the proper management of retain counts for
 133 both Cocoa and Core Foundation objects. This checking is largely based on
 134 enforcing Cocoa and Core Foundation naming conventions for Objective-C methods
 135 (Cocoa) and C functions (Core Foundation). Not strictly following these
 136 conventions can cause the analyzer to miss bugs or flag false positives.</p>
 137
 138 <p>One can educate the analyzer (and others who read your code) about methods or
 139 functions that deviate from the Cocoa and Core Foundation conventions using the
 140 attributes described here. However, you should consider using proper naming
 141 conventions or the <a
 142 href="https://clang.llvm.org/docs/LanguageExtensions.html#the-objc-method-family-attribute"><tt>objc_method_family</tt></a>
 143 attribute, if applicable.</p>
 144
 145 <h4 id="attr_ns_returns_retained">Attribute 'ns_returns_retained'
 146 (Clang-specific)</h4>
 147
 148 <p>The GCC-style (Clang-specific) attribute 'ns_returns_retained' allows one to
 149 annotate an Objective-C method or C function as returning a retained Cocoa
 150 object that the caller is responsible for releasing (via sending a
 151 <tt>release</tt> message to the object). The Foundation framework defines a
 152 macro <b><tt>NS_RETURNS_RETAINED</tt></b> that is functionally equivalent to the
 153 one shown below.</p>
 154
 155 <p><b>Placing on Objective-C methods</b>: For Objective-C methods, this
 156 annotation essentially tells the analyzer to treat the method as if its name
 157 begins with &quot;alloc&quot; or &quot;new&quot; or contains the word
 158 &quot;copy&quot;.</p>
 159
 160 <p><b>Placing on C functions</b>: For C functions returning Cocoa objects, the
 161 analyzer typically does not make any assumptions about whether or not the object
 162 is returned retained. Explicitly adding the 'ns_returns_retained' attribute to C
 163 functions allows the analyzer to perform extra checking.</p>
 164
 165 <p><b>Example</b></p>
 166
 167 <pre class="code_example">
 168 <span class="command">$ cat test.m</span>
 169 #import &lt;Foundation/Foundation.h&gt;
 170
 171 #ifndef __has_feature      // Optional.
 172 #define __has_feature(x) 0 // Compatibility with non-clang compilers.
 173 #endif
 174
 175 #ifndef NS_RETURNS_RETAINED
 176 #if __has_feature(attribute_ns_returns_retained)
 177 <span class="code_highlight">#define NS_RETURNS_RETAINED __attribute__((ns_returns_retained))</span>
 178 #else
 179 #define NS_RETURNS_RETAINED
 180 #endif
 181 #endif
 182
 183 @interface MyClass : NSObject {}
 184 - (NSString*) returnsRetained <span class="code_highlight">NS_RETURNS_RETAINED</span>;
 185 - (NSString*) alsoReturnsRetained;
 186 @end
 187
 188 @implementation MyClass
 189 - (NSString*) returnsRetained {
 190   return [[NSString alloc] initWithCString:"no leak here"];
 191 }
 192 - (NSString*) alsoReturnsRetained {
 193   return [[NSString alloc] initWithCString:"flag a leak"];
 194 }
 195 @end
 196 </pre>
 197
 198 <p>Running <tt>scan-build</tt> on this source file produces the following output:</p>
 199
 200 <img src="images/example_ns_returns_retained.png" alt="example returns retained">
 201
 202 <h4 id="attr_ns_returns_not_retained">Attribute 'ns_returns_not_retained'
 203 (Clang-specific)</h4>
 204
 205 <p>The 'ns_returns_not_retained' attribute is the complement of '<a
 206 href="#attr_ns_returns_retained">ns_returns_retained</a>'. Where a function or
 207 method may appear to obey the Cocoa conventions and return a retained Cocoa
 208 object, this attribute can be used to indicate that the object reference
 209 returned should not be considered as an &quot;owning&quot; reference being
 210 returned to the caller. The Foundation framework defines a
 211 macro <b><tt>NS_RETURNS_NOT_RETAINED</tt></b> that is functionally equivalent to
 212 the one shown below.</p>
 213
 214 <p>Usage is identical to <a
 215 href="#attr_ns_returns_retained">ns_returns_retained</a>.  When using the
 216 attribute, be sure to declare it within the proper macro that checks for
 217 its availability, as it is not available in earlier versions of the analyzer:</p>
 218
 219 <pre class="code_example">
 220 <span class="command">$ cat test.m</span>
 221 #ifndef __has_feature      // Optional.
 222 #define __has_feature(x) 0 // Compatibility with non-clang compilers.
 223 #endif
 224
 225 #ifndef NS_RETURNS_NOT_RETAINED
 226 #if __has_feature(attribute_ns_returns_not_retained)
 227 <span class="code_highlight">#define NS_RETURNS_NOT_RETAINED __attribute__((ns_returns_not_retained))</span>
 228 #else
 229 #define NS_RETURNS_NOT_RETAINED
 230 #endif
 231 #endif
 232 </pre>
 233
 234 <h4 id="attr_cf_returns_retained">Attribute 'cf_returns_retained'
 235 (Clang-specific)</h4>
 236
 237 <p>The GCC-style (Clang-specific) attribute 'cf_returns_retained' allows one to
 238 annotate an Objective-C method or C function as returning a retained Core
 239 Foundation object that the caller is responsible for releasing. The
 240 CoreFoundation framework defines a macro <b><tt>CF_RETURNS_RETAINED</tt></b>
 241 that is functionally equivalent to the one shown below.</p>
 242
 243 <p><b>Placing on Objective-C methods</b>: With respect to Objective-C methods.,
 244 this attribute is identical in its behavior and usage to 'ns_returns_retained'
 245 except for the distinction of returning a Core Foundation object instead of a
 246 Cocoa object.
 247
 248 This distinction is important for the following reason:
 249 as Core Foundation is a C API,
 250 the analyzer cannot always tell that a pointer return value refers to a
 251 Core Foundation object.
 252 In contrast, it is
 253 trivial for the analyzer to recognize if a pointer refers to a Cocoa object
 254 (given the Objective-C type system).
 255
 256 <p><b>Placing on C functions</b>: When placing the attribute
 257 'cf_returns_retained' on the declarations of C functions, the analyzer
 258 interprets the function as:</p>
 259
 260 <ol>
 261   <li>Returning a Core Foundation Object</li>
 262   <li>Treating the function as if it its name
 263 contained the keywords &quot;create&quot; or &quot;copy&quot;. This means the
 264 returned object as a +1 retain count that must be released by the caller, either
 265 by sending a <tt>release</tt> message (via toll-free bridging to an Objective-C
 266 object pointer), or calling <tt>CFRelease</tt> or a similar function.</li>
 267 </ol>
 268
 269 <p><b>Example</b></p>
 270
 271 <pre class="code_example">
 272 <span class="command">$ cat test.m</span>
 273 $ cat test.m
 274 #import &lt;Cocoa/Cocoa.h&gt;
 275
 276 #ifndef __has_feature      // Optional.
 277 #define __has_feature(x) 0 // Compatibility with non-clang compilers.
 278 #endif
 279
 280 #ifndef CF_RETURNS_RETAINED
 281 #if __has_feature(attribute_cf_returns_retained)
 282 <span class="code_highlight">#define CF_RETURNS_RETAINED __attribute__((cf_returns_retained))</span>
 283 #else
 284 #define CF_RETURNS_RETAINED
 285 #endif
 286 #endif
 287
 288 @interface MyClass : NSObject {}
 289 - (NSDate*) returnsCFRetained <span class="code_highlight">CF_RETURNS_RETAINED</span>;
 290 - (NSDate*) alsoReturnsRetained;
 291 - (NSDate*) returnsNSRetained <span class="code_highlight">NS_RETURNS_RETAINED</span>;
 292 @end
 293
 294 <span class="code_highlight">CF_RETURNS_RETAINED</span>
 295 CFDateRef returnsRetainedCFDate()  {
 296   return CFDateCreate(0, CFAbsoluteTimeGetCurrent());
 297 }
 298
 299 @implementation MyClass
 300 - (NSDate*) returnsCFRetained {
 301   return (NSDate*) returnsRetainedCFDate(); <b><i>// No leak.</i></b>
 302 }
 303
 304 - (NSDate*) alsoReturnsRetained {
 305   return (NSDate*) returnsRetainedCFDate(); <b><i>// Always report a leak.</i></b>
 306 }
 307
 308 - (NSDate*) returnsNSRetained {
 309   return (NSDate*) returnsRetainedCFDate(); <b><i>// Report a leak when using GC.</i></b>
 310 }
 311 @end
 312 </pre>
 313
 314 <p>Running <tt>scan-build</tt> on this example produces the following output:</p>
 315
 316 <img src="images/example_cf_returns_retained.png" alt="example returns retained">
 317
 318 <h4 id="attr_cf_returns_not_retained">Attribute 'cf_returns_not_retained'
 319 (Clang-specific)</h4>
 320
 321 <p>The 'cf_returns_not_retained' attribute is the complement of '<a
 322 href="#attr_cf_returns_retained">cf_returns_retained</a>'. Where a function or
 323 method may appear to obey the Core Foundation or Cocoa conventions and return
 324 a retained Core Foundation object, this attribute can be used to indicate that
 325 the object reference returned should not be considered as an
 326 &quot;owning&quot; reference being returned to the caller. The
 327 CoreFoundation framework defines a macro <b><tt>CF_RETURNS_NOT_RETAINED</tt></b>
 328 that is functionally equivalent to the one shown below.</p>
 329
 330 <p>Usage is identical to <a
 331 href="#attr_cf_returns_retained">cf_returns_retained</a>.  When using the
 332 attribute, be sure to declare it within the proper macro that checks for
 333 its availability, as it is not available in earlier versions of the analyzer:</p>
 334
 335 <pre class="code_example">
 336 <span class="command">$ cat test.m</span>
 337 #ifndef __has_feature      // Optional.
 338 #define __has_feature(x) 0 // Compatibility with non-clang compilers.
 339 #endif
 340
 341 #ifndef CF_RETURNS_NOT_RETAINED
 342 #if __has_feature(attribute_cf_returns_not_retained)
 343 <span class="code_highlight">#define CF_RETURNS_NOT_RETAINED __attribute__((cf_returns_not_retained))</span>
 344 #else
 345 #define CF_RETURNS_NOT_RETAINED
 346 #endif
 347 #endif
 348 </pre>
 349
 350 <h4 id="attr_ns_consumed">Attribute 'ns_consumed'
 351 (Clang-specific)</h4>
 352
 353 <p>The 'ns_consumed' attribute can be placed on a specific parameter in either
 354 the declaration of a function or an Objective-C method. It indicates to the
 355 static analyzer that a <tt>release</tt> message is implicitly sent to the
 356 parameter upon completion of the call to the given function or method. The
 357 Foundation framework defines a macro <b><tt>NS_RELEASES_ARGUMENT</tt></b> that
 358 is functionally equivalent to the <tt>NS_CONSUMED</tt> macro shown below.</p>
 359
 360 <p><b>Example</b></p>
 361
 362 <pre class="code_example">
 363 <span class="command">$ cat test.m</span>
 364 #ifndef __has_feature      // Optional.
 365 #define __has_feature(x) 0 // Compatibility with non-clang compilers.
 366 #endif
 367
 368 #ifndef NS_CONSUMED
 369 #if __has_feature(attribute_ns_consumed)
 370 <span class="code_highlight">#define NS_CONSUMED __attribute__((ns_consumed))</span>
 371 #else
 372 #define NS_CONSUMED
 373 #endif
 374 #endif
 375
 376 void consume_ns(id <span class="code_highlight">NS_CONSUMED</span> x);
 377
 378 void test() {
 379   id x = [[NSObject alloc] init];
 380   consume_ns(x); <b><i>// No leak!</i></b>
 381 }
 382
 383 @interface Foo : NSObject
 384 + (void) releaseArg:(id) <span class="code_highlight">NS_CONSUMED</span> x;
 385 + (void) releaseSecondArg:(id)x second:(id) <span class="code_highlight">NS_CONSUMED</span> y;
 386 @end
 387
 388 void test_method() {
 389   id x = [[NSObject alloc] init];
 390   [Foo releaseArg:x]; <b><i>// No leak!</i></b>
 391 }
 392
 393 void test_method2() {
 394   id a = [[NSObject alloc] init];
 395   id b = [[NSObject alloc] init];
 396   [Foo releaseSecondArg:a second:b]; <b><i>// 'a' is leaked, but 'b' is released.</i></b>
 397 }
 398 </pre>
 399
 400 <h4 id="attr_cf_consumed">Attribute 'cf_consumed'
 401 (Clang-specific)</h4>
 402
 403 <p>The 'cf_consumed' attribute is practically identical to <a
 404 href="#attr_ns_consumed">ns_consumed</a>. The attribute can be placed on a
 405 specific parameter in either the declaration of a function or an Objective-C
 406 method. It indicates to the static analyzer that the object reference is
 407 implicitly passed to a call to <tt>CFRelease</tt> upon completion of the call
 408 to the given function or method. The CoreFoundation framework defines a macro
 409 <b><tt>CF_RELEASES_ARGUMENT</tt></b> that is functionally equivalent to the
 410 <tt>CF_CONSUMED</tt> macro shown below.</p>
 411
 412 <p>Operationally this attribute is nearly identical to 'ns_consumed'.</p>
 413
 414 <p><b>Example</b></p>
 415
 416 <pre class="code_example">
 417 <span class="command">$ cat test.m</span>
 418 #ifndef __has_feature      // Optional.
 419 #define __has_feature(x) 0 // Compatibility with non-clang compilers.
 420 #endif
 421
 422 #ifndef CF_CONSUMED
 423 #if __has_feature(attribute_cf_consumed)
 424 <span class="code_highlight">#define CF_CONSUMED __attribute__((cf_consumed))</span>
 425 #else
 426 #define CF_CONSUMED
 427 #endif
 428 #endif
 429
 430 void consume_cf(id <span class="code_highlight">CF_CONSUMED</span> x);
 431 void consume_CFDate(CFDateRef <span class="code_highlight">CF_CONSUMED</span> x);
 432
 433 void test() {
 434   id x = [[NSObject alloc] init];
 435   consume_cf(x); <b><i>// No leak!</i></b>
 436 }
 437
 438 void test2() {
 439   CFDateRef date = CFDateCreate(0, CFAbsoluteTimeGetCurrent());
 440   consume_CFDate(date); <b><i>// No leak, including under GC!</i></b>
 441
 442 }
 443
 444 @interface Foo : NSObject
 445 + (void) releaseArg:(CFDateRef) <span class="code_highlight">CF_CONSUMED</span> x;
 446 @end
 447
 448 void test_method() {
 449   CFDateRef date = CFDateCreate(0, CFAbsoluteTimeGetCurrent());
 450   [Foo releaseArg:date]; <b><i>// No leak!</i></b>
 451 }
 452 </pre>
 453
 454 <h4 id="attr_ns_consumes_self">Attribute 'ns_consumes_self'
 455 (Clang-specific)</h4>
 456
 457 <p>The 'ns_consumes_self' attribute can be placed only on an Objective-C method
 458 declaration. It indicates that the receiver of the message is
 459 &quot;consumed&quot; (a single reference count decremented) after the message
 460 is sent. This matches the semantics of all &quot;init&quot; methods.</p>
 461
 462 <p>One use of this attribute is declare your own init-like methods that do not
 463 follow the standard Cocoa naming conventions.</p>
 464
 465 <p><b>Example</b></p>
 466
 467 <pre class="code_example">
 468 #ifndef __has_feature
 469 #define __has_feature(x) 0 // Compatibility with non-clang compilers.
 470 #endif
 471
 472 #ifndef NS_CONSUMES_SELF
 473 #if __has_feature((attribute_ns_consumes_self))
 474 <span class="code_highlight">#define NS_CONSUMES_SELF __attribute__((ns_consumes_self))</span>
 475 #else
 476 #define NS_CONSUMES_SELF
 477 #endif
 478 #endif
 479
 480 @interface MyClass : NSObject
 481 - initWith:(MyClass *)x;
 482 - nonstandardInitWith:(MyClass *)x <span class="code_highlight">NS_CONSUMES_SELF</span> NS_RETURNS_RETAINED;
 483 @end
 484 </pre>
 485
 486 <p>In this example, <tt>-nonstandardInitWith:</tt> has the same ownership
 487 semantics as the init method <tt>-initWith:</tt>. The static analyzer will
 488 observe that the method consumes the receiver, and then returns an object with
 489 a +1 retain count.</p>
 490
 491 <p>The Foundation framework defines a macro <b><tt>NS_REPLACES_RECEIVER</tt></b>
 492 which is functionally equivalent to the combination of <tt>NS_CONSUMES_SELF</tt>
 493 and <tt>NS_RETURNS_RETAINED</tt> shown above.</p>
 494
 495 <h3 id="osobject_mem">Libkern Memory Management Annotations</h3>
 496
 497 <p><a
 498   href="https://developer.apple.com/documentation/kernel/osobject?language=objc">Libkern</a>
 499 requires developers to inherit all heap allocated objects from <tt>OSObject</tt>
 500 and to perform manual reference counting.
 501 The reference counting model is very similar to MRR (manual retain-release) mode in
 502 <a href="https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/MemoryMgmt/Articles/mmRules.html">Objective-C</a>
 503 or to CoreFoundation reference counting.
 504 Freshly-allocated objects start with a reference count of 1,
 505 and calls to <tt>retain</tt> increment it,
 506 while calls to <tt>release</tt> decrement it.
 507 The object is deallocated whenever its reference count reaches zero.</p>
 508
 509 <p>Manually incrementing and decrementing reference counts is error-prone:
 510 over-retains lead to leaks, and over-releases lead to uses-after-free.
 511 The analyzer can help the programmer to check for unbalanced
 512 retain/release calls.</p>
 513
 514 <p>The reference count checking is based on the principle of
 515 <em>locality</em>: it should be possible to establish correctness
 516 (lack of leaks/uses after free) by looking at each function body,
 517 and the declarations (not the definitions) of all the functions it interacts
 518 with.</p>
 519
 520 <p>In order to support such reasoning, it should be possible to <em>summarize</em>
 521 the behavior of each function, with respect to reference count
 522 of its returned values and attributes.</p>
 523
 524 <p>By default, the following summaries are assumed:</p>
 525 <ul>
 526   <li>All functions starting with <tt>get</tt> or <tt>Get</tt>,
 527     unless they are returning subclasses of <tt>OSIterator</tt>,
 528   are assumed to be returning at +0.
 529   That is, the caller has no reference
 530   count <em>obligations</em> with respect to the reference count of the returned object
 531   and should leave it untouched.
 532   </li>
 533
 534   <li>
 535     All other functions are assumed to return at +1.
 536     That is, the caller has an <em>obligation</em> to release such objects.
 537   </li>
 538
 539   <li>
 540     Functions are assumed not to change the reference count of their parameters,
 541     including the implicit <tt>this</tt> parameter.
 542   </li>
 543 </ul>
 544
 545 <p>These summaries can be overriden with the following
 546 <a href="https://clang.llvm.org/docs/AttributeReference.html#os-returns-not-retained">attributes</a>:</p>
 547
 548 <h4 id="attr_os_returns_retained">Attribute 'os_returns_retained'</h4>
 549
 550 <p>The <tt>os_returns_retained</tt> attribute (accessed through the macro <tt>
 551 LIBKERN_RETURNS_RETAINED</tt>) plays a role identical to <a
 552 href="#attr_ns_returns_retained">ns_returns_retained</a> for functions
 553 returning <tt>OSObject</tt> subclasses.
 554 The attribute indicates that it is a callers responsibility to release the
 555 returned object.
 556 </p>
 557
 558
 559 <h4 id="attr_os_returns_not_retained">Attribute 'os_returns_not_retained'</h4>
 560
 561 <p>The <tt>os_returns_not_retained</tt> attribute (accessed through the macro <tt>
 562 LIBKERN_RETURNS_NOT_RETAINED</tt>) plays a role identical to <a
 563 href="#attr_ns_returns_not_retained">ns_returns_not_retained</a> for functions
 564 returning <tt>OSObject</tt> subclasses.
 565 The attribute indicates that the caller should not change the retain
 566 count of the returned object.
 567 </p>
 568
 569 <h5>Example</h5>
 570
 571 <pre class="code_example">
 572 class MyClass {
 573   OSObject *f;
 574   LIBKERN_RETURNS_NOT_RETAINED OSObject *myFieldGetter();
 575 }
 576
 577
 578 // Note that the annotation only has to be applied to the function declaration.
 579 OSObject * MyClass::myFieldGetter() {
 580   return f;
 581 }
 582 </pre>
 583
 584 <h4 id="attr_os_consumed">Attribute 'os_consumed'</h4>
 585
 586 <p>Similarly to <a href="#attr_ns_consumed">ns_consumed</a> attribute,
 587 <tt>os_consumed</tt> (accessed through <tt>LIBKERN_CONSUMED</tt>) attribute,
 588 applied to a parameter,
 589 indicates that the call to the function <em>consumes</em> the parameter:
 590 the callee should either release it or store it and release it in the destructor,
 591 while the caller should assume one is subtracted from the reference count
 592 after the call.</p>
 593
 594 <pre class="code_example">
 595 IOReturn addToList(LIBKERN_CONSUMED IOPMinformee *newInformee);
 596 </pre>
 597
 598 <h4 id="attr_os_consumes_this">Attribute 'os_consumes_this'</h4>
 599
 600 <p>Similarly to <a href="#attr_ns_consumes_self">ns_consumes_self</a>,
 601 the <tt>os_consumes_self</tt> attribute indicates that the method call
 602 <em>consumes</em> the implicit <tt>this</tt> argument: the caller
 603 should assume one was subtracted from the reference count of the object
 604 after the call, and the callee has on obligation to either
 605 release the argument, or store it and eventually release it in the
 606 destructor.</p>
 607
 608 <pre class="code_example">
 609 void addThisToList(OSArray *givenList) LIBKERN_CONSUMES_THIS;
 610 </pre>
 611
 612 <h4 id="os_out_parameters">Out Parameters</h4>
 613
 614 A function can also return an object to a caller by a means of an out parameter
 615 (a pointer-to-OSObject-pointer is passed, and a callee writes a pointer to an
 616 object into an argument).
 617 Currently the analyzer does not track unannotated out
 618 parameters by default, but with annotations we distinguish four separate cases:
 619
 620 <p><b>1. Non-retained out parameters</b>, identified using
 621     <tt>LIBKERN_RETURNS_NOT_RETAINED</tt> applied to parameters, e.g.:</p>
 622
 623 <pre class="code_example">
 624 void getterViaOutParam(LIBKERN_RETURNS_NOT_RETAINED OSObject **obj)
 625 </pre>
 626
 627 <p>Such functions write a non-retained object into an out parameter, and the
 628 caller has no further obligations.</p>
 629
 630 <p><b>2. Retained out parameters</b>,
 631 identified using <tt>LIBKERN_RETURNS_RETAINED</tt>:</p>
 632 <pre class="code_example">
 633 void getterViaOutParam(LIBKERN_RETURNS_NOT_RETAINED OSObject **obj)
 634 </pre>
 635 <p>
 636 In such cases a retained object is written into an out parameter, which the caller has then to release in order to avoid a leak.
 637 </p>
 638
 639 <p>These two cases are simple - but in practice a functions returning an out-parameter usually also return a return code, and then an out parameter may or may not be written, which conditionally depends on the exit code, e.g.:</p>
 640
 641 <pre class="code_example">
 642 bool maybeCreateObject(LIBKERN_RETURNS_RETAINED OSObject **obj);
 643 </pre>
 644
 645 <p>For such functions, the usual semantics is that an object is written into on "success", and not written into on "failure".<p>
 646
 647 <p>For <tt>LIBKERN_RETURNS_RETAINED</tt> we assume the following definition of
 648 success:</p>
 649
 650 <p>For functions returning <tt>OSReturn</tt> or <tt>IOReturn</tt>
 651 (any typedef to <tt>kern_return_t</tt>) success is defined as having an output of zero (<tt>kIOReturnSuccess</tt> is zero).
 652 For all others, success is non-zero (e.g. non-nullptr for pointers)</p>
 653
 654 <p><b>3. Retained out parameters on zero return</b>
 655 The annotation <tt>LIBKERN_RETURNS_RETAINED_ON_ZERO</tt> states
 656 that a retained object is written into if and only if the function returns a zero value:</p>
 657
 658 <pre class="code_example">
 659 bool OSUnserializeXML(void *data, LIBKERN_RETURNS_RETAINED_ON_ZERO OSString **errString);
 660 </pre>
 661
 662 <p>Then the caller has to release an object if the function has returned zero.</p>
 663
 664 <p><b>4. Retained out parameters on non-zero return</b>
 665 Similarly, <tt>LIBKERN_RETURNS_RETAINED_ON_NONZERO</tt> specifies that a
 666 retained object is written into the parameter if and only if the function has
 667 returned a non-zero value.</p>
 668
 669 <p>Note that for non-retained out parameters conditionals do not matter, as the
 670 caller has no obligations regardless of whether an object is written into or
 671 not.</p>
 672
 673 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
 674 <h2 id="custom_assertions">Custom Assertion Handlers</h2>
 675 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
 676
 677 <p>The analyzer exploits code assertions by pruning off paths where the
 678 assertion condition is false. The idea is capture any program invariants
 679 specified in the assertion that the developer may know but is not immediately
 680 apparent in the code itself. In this way assertions make implicit assumptions
 681 explicit in the code, which not only makes the analyzer more accurate when
 682 finding bugs, but can help others better able to understand your code as well.
 683 It can also help remove certain kinds of analyzer false positives by pruning off
 684 false paths.</p>
 685
 686 <p>In order to exploit assertions, however, the analyzer must understand when it
 687 encounters an &quot;assertion handler.&quot; Typically assertions are
 688 implemented with a macro, with the macro performing a check for the assertion
 689 condition and, when the check fails, calling an assertion handler.  For example, consider the following code
 690 fragment:</p>
 691
 692 <pre class="code_example">
 693 void foo(int *p) {
 694   assert(p != NULL);
 695 }
 696 </pre>
 697
 698 <p>When this code is preprocessed on Mac OS X it expands to the following:</p>
 699
 700 <pre class="code_example">
 701 void foo(int *p) {
 702   (__builtin_expect(!(p != NULL), 0) ? __assert_rtn(__func__, "t.c", 4, "p != NULL") : (void)0);
 703 }
 704 </pre>
 705
 706 <p>In this example, the assertion handler is <tt>__assert_rtn</tt>. When called,
 707 most assertion handlers typically print an error and terminate the program. The
 708 analyzer can exploit such semantics by ending the analysis of a path once it
 709 hits a call to an assertion handler.</p>
 710
 711 <p>The trick, however, is that the analyzer needs to know that a called function
 712 is an assertion handler; otherwise the analyzer might assume the function call
 713 returns and it will continue analyzing the path where the assertion condition
 714 failed. This can lead to false positives, as the assertion condition usually
 715 implies a safety condition (e.g., a pointer is not null) prior to performing
 716 some action that depends on that condition (e.g., dereferencing a pointer).</p>
 717
 718 <p>The analyzer knows about several well-known assertion handlers, but can
 719 automatically infer if a function should be treated as an assertion handler if
 720 it is annotated with the 'noreturn' attribute or the (Clang-specific)
 721 'analyzer_noreturn' attribute. Note that, currently, clang does not support
 722 these attributes on Objective-C methods and C++ methods.</p>
 723
 724 <h4 id="attr_noreturn">Attribute 'noreturn'</h4>
 725
 726 <p>The 'noreturn' attribute is a GCC-attribute that can be placed on the
 727 declarations of functions. It means exactly what its name implies: a function
 728 with a 'noreturn' attribute should never return.</p>
 729
 730 <p>Specific details of the syntax of using the 'noreturn' attribute can be found
 731 in <a
 732 href="https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-noreturn-function-attribute">GCC's
 733 documentation</a>.</p>
 734
 735 <p>Not only does the analyzer exploit this information when pruning false paths,
 736 but the compiler also takes it seriously and will generate different code (and
 737 possibly better optimized) under the assumption that the function does not
 738 return.</p>
 739
 740 <p><b>Example</b></p>
 741
 742 <p>On Mac OS X, the function prototype for <tt>__assert_rtn</tt> (declared in
 743 <tt>assert.h</tt>) is specifically annotated with the 'noreturn' attribute:</p>
 744
 745 <pre class="code_example">
 746 void __assert_rtn(const char *, const char *, int, const char *) <span class="code_highlight">__attribute__((__noreturn__))</span>;
 747 </pre>
 748
 749 <h4 id="attr_analyzer_noreturn">Attribute 'analyzer_noreturn' (Clang-specific)</h4>
 750
 751 <p>The Clang-specific 'analyzer_noreturn' attribute is almost identical to
 752 'noreturn' except that it is ignored by the compiler for the purposes of code
 753 generation.</p>
 754
 755 <p>This attribute is useful for annotating assertion handlers that actually
 756 <em>can</em> return, but for the purpose of using the analyzer we want to
 757 pretend that such functions do not return.</p>
 758
 759 <p>Because this attribute is Clang-specific, its use should be conditioned with
 760 the use of preprocessor macros.</p>
 761
 762 <p><b>Example</b>
 763
 764 <pre class="code_example">
 765 #ifndef CLANG_ANALYZER_NORETURN
 766 #if __has_feature(attribute_analyzer_noreturn)
 767 <span class="code_highlight">#define CLANG_ANALYZER_NORETURN __attribute__((analyzer_noreturn))</span>
 768 #else
 769 #define CLANG_ANALYZER_NORETURN
 770 #endif
 771 #endif
 772
 773 void my_assert_rtn(const char *, const char *, int, const char *) <span class="code_highlight">CLANG_ANALYZER_NORETURN</span>;
 774 </pre>
 775
 776 </div>
 777 </div>
 778 </body>
 779 </html>