<p>One can educate the analyzer (and others who read your code) about methods or
functions that deviate from the Cocoa and Core Foundation conventions using the
-attributes described here.</p>
+attributes described here. However, you should consider using proper naming
+conventions or the <a
+href="http://clang.llvm.org/docs/LanguageExtensions.html#the-objc-method-family-attribute"><tt>objc_method_family</tt></a>
+attribute, if applicable.</p>
<h4 id="attr_ns_returns_retained">Attribute 'ns_returns_retained'
(Clang-specific)</h4>
<p>The GCC-style (Clang-specific) attribute 'ns_returns_retained' allows one to
annotate an Objective-C method or C function as returning a retained Cocoa
object that the caller is responsible for releasing (via sending a
-<tt>release</tt> message to the object).</p>
+<tt>release</tt> message to the object). The Foundation framework defines a
+macro <b><tt>NS_RETURNS_RETAINED</tt></b> that is functionally equivalent to the
+one shown below.</p>
<p><b>Placing on Objective-C methods</b>: For Objective-C methods, this
annotation essentially tells the analyzer to treat the method as if its name
method may appear to obey the Cocoa conventions and return a retained Cocoa
object, this attribute can be used to indicate that the object reference
returned should not be considered as an "owning" reference being
-returned to the caller.</p>
+returned to the caller. The Foundation framework defines a
+macro <b><tt>NS_RETURNS_NOT_RETAINED</tt></b> that is functionally equivalent to
+the one shown below.</p>
<p>Usage is identical to <a
href="#attr_ns_returns_retained">ns_returns_retained</a>. When using the
<p>The GCC-style (Clang-specific) attribute 'cf_returns_retained' allows one to
annotate an Objective-C method or C function as returning a retained Core
-Foundation object that the caller is responsible for releasing.
+Foundation object that the caller is responsible for releasing. The
+CoreFoundation framework defines a macro <b><tt>CF_RETURNS_RETAINED</tt></b>
+that is functionally equivalent to the one shown below.</p>
<p><b>Placing on Objective-C methods</b>: With respect to Objective-C methods.,
this attribute is identical in its behavior and usage to 'ns_returns_retained'
method may appear to obey the Core Foundation or Cocoa conventions and return
a retained Core Foundation object, this attribute can be used to indicate that
the object reference returned should not be considered as an
-"owning" reference being returned to the caller.</p>
+"owning" reference being returned to the caller. The
+CoreFoundation framework defines a macro <b><tt>CF_RETURNS_NOT_RETAINED</tt></b>
+that is functionally equivalent to the one shown below.</p>
<p>Usage is identical to <a
href="#attr_cf_returns_retained">cf_returns_retained</a>. When using the
<h4 id="attr_ns_consumed">Attribute 'ns_consumed'
(Clang-specific)</h4>
-<p>The 'ns_consumed' attribute can be placed on a specific parameter in either the declaration of a function or an Objective-C method.
- It indicates to the static analyzer that a <tt>release</tt> message is implicitly sent to the parameter upon
- completion of the call to the given function or method.
+<p>The 'ns_consumed' attribute can be placed on a specific parameter in either
+the declaration of a function or an Objective-C method. It indicates to the
+static analyzer that a <tt>release</tt> message is implicitly sent to the
+parameter upon completion of the call to the given function or method. The
+Foundation framework defines a macro <b><tt>NS_RELEASES_ARGUMENT</tt></b> that
+is functionally equivalent to the <tt>NS_CONSUMED</tt> macro shown below.</p>
<p><b>Important note when using Garbage Collection</b>: Note that the analyzer
essentially ignores this attribute when code is compiled to use Objective-C
<h4 id="attr_cf_consumed">Attribute 'cf_consumed'
(Clang-specific)</h4>
-<p>The 'cf_consumed' attribute is practically identical to <a href="#attr_ns_consumed">ns_consumed</a>.
-The attribute can be placed on a specific parameter in either the declaration of a function or an Objective-C method.
-It indicates to the static analyzer that the object reference is implicitly passed to a call to <tt>CFRelease</tt> upon
-completion of the call to the given function or method.</p>
+<p>The 'cf_consumed' attribute is practically identical to <a
+href="#attr_ns_consumed">ns_consumed</a>. The attribute can be placed on a
+specific parameter in either the declaration of a function or an Objective-C
+method. It indicates to the static analyzer that the object reference is
+implicitly passed to a call to <tt>CFRelease</tt> upon completion of the call
+to the given function or method. The CoreFoundation framework defines a macro
+<b><tt>CF_RELEASES_ARGUMENT</tt></b> that is functionally equivalent to the
+<tt>CF_CONSUMED</tt> macro shown below.</p>
-<p>Operationally this attribute is nearly identical to ns_consumed
-with the main difference that the reference count decrement still occurs when using Objective-C garbage
-collection (which is import for Core Foundation types, which are not automatically garbage collected).</p>
+<p>Operationally this attribute is nearly identical to 'ns_consumed' with the
+main difference that the reference count decrement still occurs when using
+Objective-C garbage collection (which is import for Core Foundation types,
+which are not automatically garbage collected).</p>
<p><b>Example</b></p>
<h4 id="attr_ns_consumes_self">Attribute 'ns_consumes_self'
(Clang-specific)</h4>
-<p>The 'ns_consumes_self' attribute can be placed only on an Objective-C method declaration.
- It indicates that the receiver of the message is "consumed" (a single reference count decremented)
- after the message is sent. This matches the semantics of all "init" methods.
-</p>
+<p>The 'ns_consumes_self' attribute can be placed only on an Objective-C method
+declaration. It indicates that the receiver of the message is
+"consumed" (a single reference count decremented) after the message
+is sent. This matches the semantics of all "init" methods.</p>
-<p>One use of this attribute is declare your own init-like methods that do not follow the
- standard Cocoa naming conventions.</p>
+<p>One use of this attribute is declare your own init-like methods that do not
+follow the standard Cocoa naming conventions.</p>
<p><b>Example</b></p>
@end
</pre>
-<p>In this example, <tt>nonstandardInitWith:</tt> has the same ownership semantics as the init method <tt>initWith:</tt>.
- The static analyzer will observe that the method consumes the receiver, and then returns an object with a +1 retain count.</p>
+<p>In this example, <tt>-nonstandardInitWith:</tt> has the same ownership
+semantics as the init method <tt>-initWith:</tt>. The static analyzer will
+observe that the method consumes the receiver, and then returns an object with
+a +1 retain count.</p>
+
+<p>The Foundation framework defines a macro <b><tt>NS_REPLACES_RECEIVER</tt></b>
+which is functionally equivalent to the combination of <tt>NS_CONSUMES_SELF</tt>
+and <tt>NS_RETURNS_RETAINED</tt> shown above.</p>
+
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<h2 id="custom_assertions">Custom Assertion Handlers</h2>
<td><b>unix.cstring.NullArg</b></td><td>Check for null pointers being passed as arguments to C string functions.</td>
</table>
-<p>In addition to these the analyzer contains numerous experimental (beta) checkers.</p>
+<p>In addition to these the analyzer contains numerous experimental (alpha) checkers.</p>
<h3>Writeups with examples of some of the bugs that the analyzer finds</h3>
<ul>
<li><a href="http://www.mobileorchard.com/bug-finding-with-clang-5-resources-to-get-you-started/">Bug Finding With Clang: 5 Resources To Get You Started</a></li>
<li><a href="http://fruitstandsoftware.com/blog/index.php/2008/08/finding-memory-leaks-with-the-llvmclang-static-analyzer/#comment-2">Finding Memory Leaks With The LLVM/Clang Static Analyzer</a></li>
-<li><a href="http://www.therareair.com/howto-static-analyze-your-objective-c-code-using-the-clang-static-analyzer-tool-gallery/">HOWTO: Static Analyze Your Objective-C Code Using the Clang Static Analyzer Tool Gallery</a></li>
<li><a href="http://www.rogueamoeba.com/utm/2008/07/14/the-clang-static-analyzer/">Under the Microscope - The Clang Static Analyzer</a></li>
<li><a href="http://www.mikeash.com/?page=pyblog/friday-qa-2009-03-06-using-the-clang-static-analyzer.html">Mike Ash - Using the Clang Static Analyzer</a></li>
</ul>
<h1>C++ Support</h1>
-<p>The Clang frontend
-now <a href="http://clang.llvm.org/cxx_status.html">supports the
-majority of C++</a>. Support in the frontend for C++ language
-features, however, does not automatically translate into support for
-those features in the static analyzer. Language features need to be
-specifically modeled in the static analyzer so their semantics can be
-properly analyzed. Support for analyzing C++ and Objective-C++ files
-is currently extremely limited, and we are only encouraging those who
-are interested in contributing to the development of the analyzer to
-try this functionality out at this time.</p>
+<p>The Clang compiler <a
+href="http://clang.llvm.org/cxx_status.html">supports almost all of C++11</a>.
+Support in the frontend for C++ language features, however, does not
+automatically translate into support for those features in the static analyzer.
+Language features need to be specifically modeled in the static analyzer so
+their semantics can be properly analyzed. Support for analyzing C++ and
+Objective-C++ files is currently fairly basic.</p>
<p>Listed here are a set of open tasks that are prerequisites for
decent analysis of C++. This list is also not complete; new tasks
<ul>
<li>Control-Flow Graph Enhancements:
<ul>
- <li>Model C++ destructors</li>
- <li>Model C++ initializers (in constructors)</li>
+ <li>Model destructors for temporary objects</li>
+ <li>Model the implicit allocator call to <tt>operator new</tt></li>
</ul>
</li>
- <li>Path-Sensitive Analysis Engine (GRExprEngine):
+ <li>Path-Sensitive Analysis Engine (ExprEngine):
<ul>
- <li>Model C++ casts</li>
- <li>Model C++ constructors</li>
- <li>Model C++ destructors</li>
- <li>Model <tt>new</tt> and <tt>delete</tt></li>
+ <li>Allow constructors to be inlined</li>
+ <li>Allow destructors to be inlined</li>
+ <li>Fully model <tt>new</tt> and <tt>delete</tt></li>
+ <li>Track type info through casts more precisely</li>
+ </ul>
+ </li>
+ <li>Checkers:
+ <ul>
+ <li>Check that <tt>new</tt> and <tt>delete</tt> are correctly paired</li>
+ <li>For more ideas, see the <a href="potential_checkers.html">list of potential checkers</a></li>
</ul>
</li>
</ul>
<h1>Clang Static Analyzer</h1>
-<p>The Clang Static Analyzer is source code analysis tool that find bugs in C
-and Objective-C programs.</p>
+<p>The Clang Static Analyzer is a source code analysis tool that finds bugs in
+C, C++, and Objective-C programs.</p>
-<p>Currently it can be run either as a <a href="/scan-build.html">standalone
-tool</a> or <a href="/xcode.html">within Xcode</a>. The standalone tool is
-invoked from the command-line, and is intended to be run in tandem with a build
+<p>Currently it can be run either as a <a href="scan-build.html">standalone
+tool</a> or <a href="xcode.html">within Xcode</a>. The standalone tool is
+invoked from the command line, and is intended to be run in tandem with a build
of a codebase.</p>
<p>The analyzer is 100% open source and is part of the <a
</td><td style="padding-left:10px">
<a href="images/analyzer_xcode.png"><img src="images/analyzer_xcode.png" width="450" alt="analyzer in xcode"></a>
-<div style="text-align:center"><b>Viewing static analyzer results in Xcode 3.2</b></div>
+<div style="text-align:center"><b>Viewing static analyzer results in Xcode</b></div>
<a href="images/analyzer_html.png"><img src="images/analyzer_html.png" width="450" alt="analyzer in browser"></a>
<div style="text-align:center"><b>Viewing static analyzer results in a web browser</b></div>
</td></tr></table>
<h2 id="StaticAnalysis">What is Static Analysis?</h2>
-<p>The term "static analysis" is conflated, but here we use it to mean
+<p>The term "static analysis" is conflated, but here we use it to mean
a collection of algorithms and techniques used to analyze source code in order
to automatically find bugs. The idea is similar in spirit to compiler warnings
(which can be useful for finding coding errors) but to take that idea a step
<p>Static analysis bug-finding tools have evolved over the last several decades
from basic syntactic checkers to those that find deep bugs by reasoning about
the semantics of code. The goal of the Clang Static Analyzer is to provide a
-industrial-quality static analysis framework for analyzing C and Objective-C
-programs that is freely available, extensible, and has a high quality of
-implementation.</p>
+industrial-quality static analysis framework for analyzing C, C++, and
+Objective-C programs that is freely available, extensible, and has a high quality of implementation.</p>
<h3 id="Clang">Part of Clang and LLVM</h3>
<h3>Work-in-Progress</h3>
-<p>The analyzer is a continuous work-in-progress.
-There are many planned enhancements to improve both the precision and scope of
-its analysis algorithms as well as the kinds bugs it will find. While there are
-fundamental limitations to what static analysis can do, we have a long way to go
-before hitting that wall.</p>
+<p>The analyzer is a continuous work-in-progress. There are many planned
+enhancements to improve both the precision and scope of its analysis algorithms
+as well as the kinds of bugs it will find. While there are fundamental
+limitations to what static analysis can do, we have a long way to go before
+hitting that wall.</p>
<h3>Slower than Compilation</h3>
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
- <title>Build and Analyze: running the analyzer within Xcode</title>
+ <title>Running the analyzer within Xcode</title>
<link type="text/css" rel="stylesheet" href="content.css">
<link type="text/css" rel="stylesheet" href="menu.css">
<script type="text/javascript" src="scripts/menu.js"></script>
<!--#include virtual="menu.html.incl"-->
<div id="content">
-<h1>Build and Analyze: running the analyzer within Xcode</h1>
+<h1>Running the analyzer within Xcode</h1>
<table style="margin-top:0px" width="100%" border="0" cellpadding="0px" cellspacing="0">
<tr><td>
<h3>What is it?</h3>
-<p><i>Build and Analyze</i> is an Xcode feature (introduced in Xcode 3.2) that
-allows users to run the Clang Static Analyzer <a
-href="http://developer.apple.com/mac/library/featuredarticles/StaticAnalysis/index.html">directly
+
+<p>Since Xcode 3.2, users have been able to run the Clang Static Analyzer
+<a
+href="https://developer.apple.com/library/mac/documentation/ToolsLanguages/Conceptual/Xcode4UserGuide/060-Debug_Your_App/debug_app.html#//apple_ref/doc/uid/TP40010215-CH3-SW17">directly
within Xcode</a>.</p>
<p>It integrates directly with the Xcode build system and
single keystroke or mouse click.</li>
<li><b>Transparency:</b> Works effortlessly with Xcode projects (including iPhone projects).
<li><b>Cons:</b> Doesn't work well with non-Xcode projects. For those,
- consider using <a href="/scan-build.html"><b>scan-build</b></a>.
+ consider using <a href="scan-build.html"><b>scan-build</b></a>.
</ul>
<h2>Getting Started</h2>
-<p>Xcode 3.2 is available as a free download from Apple, with <a
-href="http://developer.apple.com/mac/library/featuredarticles/StaticAnalysis/index.html">instructions available</a>
-for using <i>Build and Analyze</i>.</p>
+<p>Xcode is available as a free download from Apple on the <a
+href="https://itunes.apple.com/us/app/xcode/id497799835?mt=12">Mac
+App Store</a>, with <a
+href="https://developer.apple.com/library/mac/documentation/ToolsLanguages/Conceptual/Xcode4UserGuide/060-Debug_Your_App/debug_app.html#//apple_ref/doc/uid/TP40010215-CH3-SW17">instructions
+available</a> for using the analyzer.</p>
-<h2>Using open source analyzer builds with <i>Build and Analyze</i></h2>
+<h2>Using open source analyzer builds with Xcode</h2>
<p>By default, Xcode uses the version of <tt>clang</tt> that came bundled with
-it to provide the results for <i>Build and Analyze</i>. It is possible to change
-Xcode's behavior to use an alternate version of <tt>clang</tt> for this purpose
-while continuing to use the <tt>clang</tt> that came with Xcode for compiling
-projects.</p>
+it to analyze your code. It is possible to change Xcode's behavior to use an
+alternate version of <tt>clang</tt> for this purpose while continuing to use
+the <tt>clang</tt> that came with Xcode for compiling projects.</p>
<h3>Why try open source builds?</h3>
<p>Starting with analyzer build checker-234, analyzer builds contain a command
line utility called <tt>set-xcode-analyzer</tt> that allows users to change what
-copy of <tt>clang</tt> that Xcode uses for <i>Build and Analyze</i>:</p>
+copy of <tt>clang</tt> that Xcode uses for analysis:</p>
<pre class="code_example">
$ <b>set-xcode-analyzer -h</b>
</pre>
<p>Operationally, <b>set-xcode-analyzer</b> edits Xcode's configuration files
-(in <tt>/Developer</tt>) to point it to use the version of <tt>clang</tt> you
-specify for static analysis. Within this model it provides you two basic modes:</p>
+to point it to use the version of <tt>clang</tt> you specify for static
+analysis. Within this model it provides you two basic modes:</p>
<ul>
<li><b>--use-xcode-clang</b>: Switch Xcode (back) to using the <tt>clang</tt> that came bundled with it for static analysis.</li>
<h4>Things to keep in mind</h4>
<ul>
-<li>You should quit Xcode prior to running <tt>set-xcode-analyzer</tt>.</li>
-<li>You will need to run <tt>set-xcode-analyzer</tt> under <b><tt>sudo</tt></b>
- in order to have write privileges to modify the Xcode configuration files.</li>
+ <li>You should quit Xcode prior to running <tt>set-xcode-analyzer</tt>.</li> <li>You will need to run <tt>set-xcode-analyzer</tt> under
+<b><tt>sudo</tt></b> in order to have write privileges to modify the Xcode
+configuration files.</li>
</ul>
<h4>Examples</h4>
-<p><b>Example 1</b>: Telling Xcode to use checker-235 for <i>Build and Analyze</i>:</p>
+<p><b>Example 1</b>: Telling Xcode to use checker-235:</p>
<pre class="code_example">
$ pwd
projects / clang / commitdiff