Clang supports additional attributes that are useful for documenting program -invariants and rules for static analysis tools. The extensions documented here -are used by the path-sensitive static analyzer -engine that is part of Clang's Analysis library.
+invariants and rules for static analysis tools. These extensions are used by the +path-sensitive static analyzer +engine that is part of Clang's Analysis library and documented on +their own page. + -Clang's static analysis engine understands the standard noreturn -attribute. This attribute, which is typically affixed to a function prototype, -indicates that a call to a given function never returns. Function prototypes for -common functions like exit are typically annotated with this attribute, -as well as a variety of common assertion handlers. Users can educate the static -analyzer about their own custom assertion handles (thus cutting down on false -positives due to false paths) by marking their own "panic" functions -with this attribute.
- -While useful, noreturn is not applicable in all cases. Sometimes -there are special functions that for all intents and purposes should be -considered panic functions (i.e., they are only called when an internal program -error occurs) but may actually return so that the program can fail gracefully. -The analyzer_noreturn attribute allows one to annotate such functions -as being interpreted as "no return" functions by the analyzer (thus -pruning bogus paths) but will not affect compilation (as in the case of -noreturn).
- -Usage: The analyzer_noreturn attribute can be placed in the -same places where the noreturn attribute can be placed. It is commonly -placed at the end of function prototypes:
- -- void foo() __attribute__((analyzer_noreturn)); -- -
Query for this feature with -__has_attribute(analyzer_noreturn).
- -Many methods in Objective-C have conventional meanings determined
-by their selectors. For the purposes of static analysis, it is
-sometimes useful to be able to mark a method as having a particular
-conventional meaning despite not having the right selector, or as not
-having the conventional meaning that its selector would suggest.
-For these use cases, we provide an attribute to specifically describe
-the method family
that a method belongs to.
Usage: __attribute__((objc_method_family(X))), -where X is one of none, alloc, copy, -init, mutableCopy, or new. This attribute -can only be placed at the end of a method declaration:
- -- - (NSString*) initMyStringValue __attribute__((objc_method_family(none))); -- -
Users who do not wish to change the conventional meaning of a -method, and who merely want to document its non-standard retain and -release semantics, should use the -retaining behavior attributes -described below.
- -Query for this feature with -__has_attribute(objc_method_family).
- -In Objective-C, functions and methods are generally assumed to take -and return objects with +0 retain counts, with some exceptions for -special methods like +alloc and init. However, -there are exceptions, and so Clang provides attributes to allow these -exceptions to be documented, which helps the analyzer find leaks (and -ignore non-leaks). Some exceptions may be better described using -the objc_method_family -attribute instead.
- -Usage: The ns_returns_retained, ns_returns_not_retained, -ns_returns_autoreleased, cf_returns_retained, -and cf_returns_not_retained attributes can be placed on -methods and functions that return Objective-C or CoreFoundation -objects. They are commonly placed at the end of a function prototype -or method declaration:
- -- id foo() __attribute__((ns_returns_retained)); - - - (NSString*) bar: (int) x __attribute__((ns_returns_retained)); -- -
The *_returns_retained attributes specify that the -returned object has a +1 retain count. -The *_returns_not_retained attributes specify that the return -object has a +0 retain count, even if the normal convention for its -selector would be +1. ns_returns_autoreleased specifies that the -returned object is +0, but is guaranteed to live at least as long as the -next flush of an autorelease pool.
- -Usage: The ns_consumed and cf_consumed -attributes can be placed on an parameter declaration; they specify -that the argument is expected to have a +1 retain count, which will be -balanced in some way by the function or method. -The ns_consumes_self attribute can only be placed on an -Objective-C method; it specifies that the method expects -its self parameter to have a +1 retain count, which it will -balance in some way.
- -- void foo(__attribute__((ns_consumed)) NSString *string); - - - (void) bar __attribute__((ns_consumes_self)); - - (void) baz: (id) __attribute__((ns_consumed)) x; -- -
Query for these features with __has_attribute(ns_consumed), -__has_attribute(ns_returns_retained), etc.
-