17
17
< h1 > Source Annotations</ h1 >
18
18
19
19
< p > The Clang frontend supports several source-level annotations in the form of
20
- < a href ="http ://gcc.gnu.org/onlinedocs/gcc/Attribute-Syntax.html "> GCC-style
20
+ < a href ="https ://gcc.gnu.org/onlinedocs/gcc/Attribute-Syntax.html "> GCC-style
21
21
attributes</ a > and pragmas that can help make using the Clang Static Analyzer
22
22
more useful. These annotations can both help suppress false positives as well as
23
23
enhance the analyzer's ability to find bugs.</ p >
24
24
25
25
< p > This page gives a practical overview of such annotations. For more technical
26
26
specifics regarding Clang-specific annotations please see the Clang's list of < a
27
- href ="http ://clang.llvm.org/docs/LanguageExtensions.html "> language
27
+ href ="https ://clang.llvm.org/docs/LanguageExtensions.html "> language
28
28
extensions</ a > . Details of "standard" GCC attributes (that Clang also
29
- supports) can be found in the < a href ="http ://gcc.gnu.org/onlinedocs/gcc/ "> GCC
29
+ supports) can be found in the < a href ="https ://gcc.gnu.org/onlinedocs/gcc/ "> GCC
30
30
manual</ a > , with the majority of the relevant attributes being in the section on
31
- < a href ="http ://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html "> function
31
+ < a href ="https ://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html "> function
32
32
attributes</ a > .</ p >
33
33
34
34
< p > Note that attributes that are labeled < b > Clang-specific</ b > are not
@@ -68,7 +68,7 @@ <h4>Specific Topics</h4>
68
68
< li > < a href ="#attr_os_consumes_this "> Attribute 'os_consumes_this'</ a > </ li >
69
69
< li > < a href ="#os_out_parameters "> Out Parameters</ a > </ li >
70
70
</ ul >
71
-
71
+
72
72
</ li >
73
73
</ ul >
74
74
</ li >
@@ -91,7 +91,7 @@ <h4 id="attr_nonnull">Attribute 'nonnull'</h4>
91
91
< p > The analyzer recognizes the GCC attribute 'nonnull', which indicates that a
92
92
function expects that a given function parameter is not a null pointer. Specific
93
93
details of the syntax of using the 'nonnull' attribute can be found in < a
94
- href ="http ://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html#index-g_t_0040code_007bnonnull_007d -function-attribute-2263 "> GCC's
94
+ href ="https ://gcc.gnu.org/onlinedocs/gcc/Common- Function-Attributes.html#index-nonnull -function-attribute "> GCC's
95
95
documentation</ a > .</ p >
96
96
97
97
< p > Both the Clang compiler and GCC will flag warnings for simple cases where a
@@ -108,7 +108,7 @@ <h4 id="attr_nonnull">Attribute 'nonnull'</h4>
108
108
int bar(int*p, int q, int *r) __attribute__((nonnull(1,3)));
109
109
110
110
int foo(int *p, int *q) {
111
- return !p ? bar(q, 2, p)
111
+ return !p ? bar(q, 2, p)
112
112
: bar(p, 2, q);
113
113
}
114
114
</ pre >
@@ -138,8 +138,8 @@ <h3 id="cocoa_mem">Cocoa & Core Foundation Memory Management
138
138
< p > One can educate the analyzer (and others who read your code) about methods or
139
139
functions that deviate from the Cocoa and Core Foundation conventions using the
140
140
attributes described here. However, you should consider using proper naming
141
- conventions or the < a
142
- href ="http ://clang.llvm.org/docs/LanguageExtensions.html#the-objc-method-family-attribute "> < tt > objc_method_family</ tt > </ a >
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
143
attribute, if applicable.</ p >
144
144
145
145
< h4 id ="attr_ns_returns_retained "> Attribute 'ns_returns_retained'
@@ -236,7 +236,7 @@ <h4 id="attr_cf_returns_retained">Attribute 'cf_returns_retained'
236
236
237
237
< p > The GCC-style (Clang-specific) attribute 'cf_returns_retained' allows one to
238
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
239
+ Foundation object that the caller is responsible for releasing. The
240
240
CoreFoundation framework defines a macro < b > < tt > CF_RETURNS_RETAINED</ tt > </ b >
241
241
that is functionally equivalent to the one shown below.</ p >
242
242
@@ -323,7 +323,7 @@ <h4 id="attr_cf_returns_not_retained">Attribute 'cf_returns_not_retained'
323
323
method may appear to obey the Core Foundation or Cocoa conventions and return
324
324
a retained Core Foundation object, this attribute can be used to indicate that
325
325
the object reference returned should not be considered as an
326
- "owning" reference being returned to the caller. The
326
+ "owning" reference being returned to the caller. The
327
327
CoreFoundation framework defines a macro < b > < tt > CF_RETURNS_NOT_RETAINED</ tt > </ b >
328
328
that is functionally equivalent to the one shown below.</ p >
329
329
@@ -353,8 +353,8 @@ <h4 id="attr_ns_consumed">Attribute 'ns_consumed'
353
353
< p > The 'ns_consumed' attribute can be placed on a specific parameter in either
354
354
the declaration of a function or an Objective-C method. It indicates to the
355
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
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
358
is functionally equivalent to the < tt > NS_CONSUMED</ tt > macro shown below.</ p >
359
359
360
360
< p > < b > Example</ b > </ p >
@@ -408,7 +408,7 @@ <h4 id="attr_cf_consumed">Attribute 'cf_consumed'
408
408
to the given function or method. The CoreFoundation framework defines a macro
409
409
< b > < tt > CF_RELEASES_ARGUMENT</ tt > </ b > that is functionally equivalent to the
410
410
< tt > CF_CONSUMED</ tt > macro shown below.</ p >
411
-
411
+
412
412
< p > Operationally this attribute is nearly identical to 'ns_consumed'.</ p >
413
413
414
414
< p > < b > Example</ b > </ p >
@@ -438,7 +438,7 @@ <h4 id="attr_cf_consumed">Attribute 'cf_consumed'
438
438
void test2() {
439
439
CFDateRef date = CFDateCreate(0, CFAbsoluteTimeGetCurrent());
440
440
consume_CFDate(date); < b > < i > // No leak, including under GC!</ i > </ b >
441
-
441
+
442
442
}
443
443
444
444
@interface Foo : NSObject
@@ -463,7 +463,7 @@ <h4 id="attr_ns_consumes_self">Attribute 'ns_consumes_self'
463
463
follow the standard Cocoa naming conventions.</ p >
464
464
465
465
< p > < b > Example</ b > </ p >
466
-
466
+
467
467
< pre class ="code_example ">
468
468
#ifndef __has_feature
469
469
#define __has_feature(x) 0 // Compatibility with non-clang compilers.
@@ -573,8 +573,8 @@ <h5>Example</h5>
573
573
OSObject *f;
574
574
LIBKERN_RETURNS_NOT_RETAINED OSObject *myFieldGetter();
575
575
}
576
-
577
-
576
+
577
+
578
578
// Note that the annotation only has to be applied to the function declaration.
579
579
OSObject * MyClass::myFieldGetter() {
580
580
return f;
@@ -633,7 +633,7 @@ <h4 id="os_out_parameters">Out Parameters</h4>
633
633
void getterViaOutParam(LIBKERN_RETURNS_NOT_RETAINED OSObject **obj)
634
634
</ pre >
635
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.
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
637
</ p >
638
638
639
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 >
@@ -718,7 +718,7 @@ <h2 id="custom_assertions">Custom Assertion Handlers</h2>
718
718
< p > The analyzer knows about several well-known assertion handlers, but can
719
719
automatically infer if a function should be treated as an assertion handler if
720
720
it is annotated with the 'noreturn' attribute or the (Clang-specific)
721
- 'analyzer_noreturn' attribute. Note that, currently, clang does not support
721
+ 'analyzer_noreturn' attribute. Note that, currently, clang does not support
722
722
these attributes on Objective-C methods and C++ methods.</ p >
723
723
724
724
< h4 id ="attr_noreturn "> Attribute 'noreturn'</ h4 >
@@ -729,7 +729,7 @@ <h4 id="attr_noreturn">Attribute 'noreturn'</h4>
729
729
730
730
< p > Specific details of the syntax of using the 'noreturn' attribute can be found
731
731
in < a
732
- href ="http ://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html#index-g_t_0040code_007bnoreturn_007d -function-attribute-2264 "> GCC's
732
+ href ="https ://gcc.gnu.org/onlinedocs/gcc/Common- Function-Attributes.html#index-noreturn -function-attribute "> GCC's
733
733
documentation</ a > .</ p >
734
734
735
735
< p > Not only does the analyzer exploit this information when pruning false paths,
0 commit comments