Vendor import of clang release_32 branch r168974 (effectively, 3.2 RC2):

http://llvm.org/svn/llvm-project/cfe/branches/release_32@168974

1 files changed, 34 insertions, 15 deletions

diff --git a/docs/AddressSanitizer.html b/docs/AddressSanitizer.html
index 98ea934..397eafc 100644
--- a/docs/AddressSanitizer.html
+++ b/docs/AddressSanitizer.html
@@ -45,17 +45,21 @@ The tool can detect the following types of bugs:
 Typical slowdown introduced by AddressSanitizer is <b>2x</b>.
 
 <h2 id="howtobuild">How to build</h2>
-Follow the <a href="../get_started.html">clang build instructions</a>. <BR>
-Note: CMake build does not work yet.
-See <a href="http://llvm.org/bugs/show_bug.cgi?id=12272">bug 12272</a>.
+Follow the <a href="../get_started.html">clang build instructions</a>.
+CMake build is supported.<BR>
 
 <h2 id="usage">Usage</h2>
-Simply compile and link your program with <tt>-faddress-sanitizer</tt> flag. <BR>
+Simply compile and link your program with <tt>-fsanitize=address</tt> flag. <BR>
+The AddressSanitizer run-time library should be linked to the final executable,
+so make sure to use <tt>clang</tt> (not <tt>ld</tt>) for the final link step.<BR>
+When linking shared libraries, the AddressSanitizer run-time is not linked,
+so <tt>-Wl,-z,defs</tt> may cause link errors (don't use it with AddressSanitizer). <BR>
+
 To get a reasonable performance add <tt>-O1</tt> or higher. <BR>
 To get nicer stack traces in error messages add
 <tt>-fno-omit-frame-pointer</tt>. <BR>
 To get perfect stack traces you may need to disable inlining (just use <tt>-O1</tt>) and tail call
-elimination (</tt>-fno-optimize-sibling-calls</tt>).
+elimination (<tt>-fno-optimize-sibling-calls</tt>).
 
 <pre>
 % cat example_UseAfterFree.cc
@@ -67,7 +71,15 @@ int main(int argc, char **argv) {
 </pre>
 
 <pre>
-% clang -O1 -g -faddress-sanitizer -fno-omit-frame-pointer example_UseAfterFree.cc
+# Compile and link
+% clang -O1 -g -fsanitize=address -fno-omit-frame-pointer example_UseAfterFree.cc
+</pre>
+OR
+<pre>
+# Compile
+% clang -O1 -g -fsanitize=address -fno-omit-frame-pointer -c example_UseAfterFree.cc
+# Link
+% clang -g -fsanitize=address example_UseAfterFree.o
 </pre>
 
 If a bug is detected, the program will print an error message to stderr and exit with a
@@ -93,6 +105,13 @@ previously allocated by thread T0 here:
 ==9442== ABORTING
 </pre>
 
+AddressSanitizer exits on the first detected error. This is by design.
+One reason: it makes the generated code smaller and faster (both by ~5%).
+Another reason: this makes fixing bugs unavoidable. With Valgrind, it is often
+the case that users treat Valgrind warnings as false positives
+(which they are not) and don't fix them.
+
+
 <h3 id="has_feature">__has_feature(address_sanitizer)</h3>
 In some cases one may need to execute different code depending on whether
 AddressSanitizer is enabled.
@@ -107,8 +126,8 @@ can be used for this purpose.
 </pre>
 
 <h3 id="no_address_safety_analysis">__attribute__((no_address_safety_analysis))</h3>
-Some code should not be instrumentated by AddressSanitizer.
-One may use the function attribute 
+Some code should not be instrumented by AddressSanitizer.
+One may use the function attribute
 <a href="LanguageExtensions.html#address_sanitizer">
   <tt>no_address_safety_analysis</tt></a>
 to disable instrumentation of a particular function.
@@ -118,18 +137,18 @@ Note: currently, this attribute will be lost if the function is inlined.
 
 <h2 id="platforms">Supported Platforms</h2>
 AddressSanitizer is supported on
-<ul><li>Linux x86_64 (tested on Ubuntu 10.04).
-<li>MacOS 10.6 and 10.7 (i386/x86_64).
+<ul><li>Linux i386/x86_64 (tested on Ubuntu 10.04 and 12.04).
+<li>MacOS 10.6, 10.7 and 10.8 (i386/x86_64).
 </ul>
-Support for Linux i386/ARM is in progress
+Support for Linux ARM (and Android ARM) is in progress
 (it may work, but is not guaranteed too).
 
 
 <h2 id="limitations">Limitations</h2>
 <ul>
 <li> AddressSanitizer uses more real memory than a native run.
-How much -- depends on the allocations sizes. The smaller the
-allocations you make the bigger the overhead.
+Exact overhead depends on the allocations sizes. The smaller the
+allocations you make the bigger the overhead is.
 <li> AddressSanitizer uses more stack memory. We have seen up to 3x increase.
 <li> On 64-bit platforms AddressSanitizer maps (but not reserves)
 16+ Terabytes of virtual address space.
@@ -140,8 +159,8 @@ This means that tools like <tt>ulimit</tt> may not work as usually expected.
 
 <h2 id="status">Current Status</h2>
 AddressSanitizer is fully functional on supported platforms starting from LLVM 3.1.
-However, the test suite is not fully integrated yet and we lack the testing
-process (buildbots).
+The test suite is integrated into CMake build and can be run with
+<tt>make check-asan</tt> command.
 
 <h2 id="moreinfo">More Information</h2>
 <a href="http://code.google.com/p/address-sanitizer/">http://code.google.com/p/address-sanitizer</a>.