| blob | bf0076e5142782400dc3c0d5112342027c4f5ded |
3 <html>
4 <head>
9 </head>
10 <body>
13 <!--#include virtual="menu.html.incl"-->
19 <p>The Clang frontend supports several source-level annotations in the form of
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>
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
30 manual</a>, with the majority of the relevant attributes being in the section on
35 recognized by GCC. Their use can be conditioned using preprocessor macros
36 (examples included on this page).</p>
40 <ul>
42 <ul>
44 <ul>
46 </ul>
47 </li>
48 </ul>
49 </li>
51 <ul>
53 <ul>
61 </ul>
62 </li>
64 <ul>
70 </ul>
72 </li>
73 </ul>
74 </li>
76 <ul>
79 </ul>
80 </li>
81 </ul>
83 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
85 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
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
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>
110 int foo(int *p, int *q) {
111 return !p ? bar(q, 2, p)
112 : bar(p, 2, q);
113 }
114 </pre>
117 output:</p>
121 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
123 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
126 Annotations</h3>
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>
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>
146 (Clang-specific)</h4>
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
153 one shown below.</p>
156 annotation essentially tells the analyzer to treat the method as if its name
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>
171 #ifndef __has_feature // Optional.
172 #define __has_feature(x) 0 // Compatibility with non-clang compilers.
173 #endif
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
183 @interface MyClass : NSObject {}
185 - (NSString*) alsoReturnsRetained;
186 @end
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>
203 (Clang-specific)</h4>
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
210 returned to the caller. The Foundation framework defines a
212 the one shown below.</p>
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>
221 #ifndef __has_feature // Optional.
222 #define __has_feature(x) 0 // Compatibility with non-clang compilers.
223 #endif
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>
235 (Clang-specific)</h4>
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
241 that is functionally equivalent to the one shown below.</p>
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.
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).
257 'cf_returns_retained' on the declarations of C functions, the analyzer
258 interprets the function as:</p>
260 <ol>
262 <li>Treating the function as if it its name
264 returned object as a +1 retain count that must be released by the caller, either
267 </ol>
273 $ cat test.m
276 #ifndef __has_feature // Optional.
277 #define __has_feature(x) 0 // Compatibility with non-clang compilers.
278 #endif
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
288 @interface MyClass : NSObject {}
290 - (NSDate*) alsoReturnsRetained;
292 @end
295 CFDateRef returnsRetainedCFDate() {
296 return CFDateCreate(0, CFAbsoluteTimeGetCurrent());
297 }
299 @implementation MyClass
300 - (NSDate*) returnsCFRetained {
302 }
304 - (NSDate*) alsoReturnsRetained {
306 }
308 - (NSDate*) returnsNSRetained {
310 }
311 @end
312 </pre>
319 (Clang-specific)</h4>
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
328 that is functionally equivalent to the one shown below.</p>
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>
337 #ifndef __has_feature // Optional.
338 #define __has_feature(x) 0 // Compatibility with non-clang compilers.
339 #endif
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>
351 (Clang-specific)</h4>
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
356 parameter upon completion of the call to the given function or method. The
364 #ifndef __has_feature // Optional.
365 #define __has_feature(x) 0 // Compatibility with non-clang compilers.
366 #endif
368 #ifndef NS_CONSUMED
369 #if __has_feature(attribute_ns_consumed)
371 #else
372 #define NS_CONSUMED
373 #endif
374 #endif
378 void test() {
379 id x = [[NSObject alloc] init];
381 }
383 @interface Foo : NSObject
386 @end
388 void test_method() {
389 id x = [[NSObject alloc] init];
391 }
393 void test_method2() {
394 id a = [[NSObject alloc] init];
395 id b = [[NSObject alloc] init];
397 }
398 </pre>
401 (Clang-specific)</h4>
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
408 to the given function or method. The CoreFoundation framework defines a macro
418 #ifndef __has_feature // Optional.
419 #define __has_feature(x) 0 // Compatibility with non-clang compilers.
420 #endif
422 #ifndef CF_CONSUMED
423 #if __has_feature(attribute_cf_consumed)
425 #else
426 #define CF_CONSUMED
427 #endif
428 #endif
433 void test() {
434 id x = [[NSObject alloc] init];
436 }
438 void test2() {
439 CFDateRef date = CFDateCreate(0, CFAbsoluteTimeGetCurrent());
442 }
444 @interface Foo : NSObject
446 @end
448 void test_method() {
449 CFDateRef date = CFDateCreate(0, CFAbsoluteTimeGetCurrent());
451 }
452 </pre>
455 (Clang-specific)</h4>
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
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>
468 #ifndef __has_feature
469 #define __has_feature(x) 0 // Compatibility with non-clang compilers.
470 #endif
472 #ifndef NS_CONSUMES_SELF
473 #if __has_feature((attribute_ns_consumes_self))
475 #else
476 #define NS_CONSUMES_SELF
477 #endif
478 #endif
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>
488 observe that the method consumes the receiver, and then returns an object with
497 <p><a
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,
507 The object is deallocated whenever its reference count reaches zero.</p>
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>
514 <p>The reference count checking is based on the principle of
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>
521 the behavior of each function, with respect to reference count
522 of its returned values and attributes.</p>
525 <ul>
528 are assumed to be returning at +0.
529 That is, the caller has no reference
531 and should leave it untouched.
532 </li>
534 <li>
535 All other functions are assumed to return at +1.
537 </li>
539 <li>
540 Functions are assumed not to change the reference count of their parameters,
542 </li>
543 </ul>
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>
554 The attribute indicates that it is a callers responsibility to release the
555 returned object.
556 </p>
565 The attribute indicates that the caller should not change the retain
566 count of the returned object.
567 </p>
572 class MyClass {
573 OSObject *f;
574 LIBKERN_RETURNS_NOT_RETAINED OSObject *myFieldGetter();
575 }
578 // Note that the annotation only has to be applied to the function declaration.
579 OSObject * MyClass::myFieldGetter() {
580 return f;
581 }
582 </pre>
588 applied to a 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>
595 IOReturn addToList(LIBKERN_CONSUMED IOPMinformee *newInformee);
596 </pre>
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>
609 void addThisToList(OSArray *givenList) LIBKERN_CONSUMES_THIS;
610 </pre>
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:
624 void getterViaOutParam(LIBKERN_RETURNS_NOT_RETAINED OSObject **obj)
625 </pre>
627 <p>Such functions write a non-retained object into an out parameter, and the
628 caller has no further obligations.</p>
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>
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>
642 bool maybeCreateObject(LIBKERN_RETURNS_RETAINED OSObject **obj);
643 </pre>
645 <p>For such functions, the usual semantics is that an object is written into on "success", and not written into on "failure".<p>
648 success:</p>
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>
656 that a retained object is written into if and only if the function returns a zero value:</p>
659 bool OSUnserializeXML(void *data, LIBKERN_RETURNS_RETAINED_ON_ZERO OSString **errString);
660 </pre>
666 retained object is written into the parameter if and only if the function has
667 returned a non-zero value.</p>
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>
673 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
675 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
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>
686 <p>In order to exploit assertions, however, the analyzer must understand when it
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>
693 void foo(int *p) {
694 assert(p != NULL);
695 }
696 </pre>
701 void foo(int *p) {
703 }
704 </pre>
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>
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>
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>
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>
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
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>
746 void __assert_rtn(const char *, const char *, int, const char *) <span class="code_highlight">__attribute__((__noreturn__))</span>;
747 </pre>
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>
755 <p>This attribute is useful for annotating assertion handlers that actually
757 pretend that such functions do not return.</p>
759 <p>Because this attribute is Clang-specific, its use should be conditioned with
760 the use of preprocessor macros.</p>
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
773 void my_assert_rtn(const char *, const char *, int, const char *) <span class="code_highlight">CLANG_ANALYZER_NORETURN</span>;
774 </pre>
776 </div>
777 </div>
778 </body>
779 </html>