Debian Codegraph @

llvm-project/clang/www/analyzer/annotations.html

raw
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>