From: Kostya Serebryany <kcc@google.com>
Date: Mon, 12 Dec 2011 23:22:31 +0000 (+0000)
Subject: [asan] update asan docs
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=2e1732299461634b9791ddfe6e3770c6be3a3675;p=clang

[asan] update asan docs

git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@146446 91177308-0d34-0410-b5e6-96231b3b80d8
---

diff --git a/docs/AddressSanitizer.html b/docs/AddressSanitizer.html
index c6a1850f46..e6f7e99047 100644
--- a/docs/AddressSanitizer.html
+++ b/docs/AddressSanitizer.html
@@ -22,30 +22,68 @@
 <h1>AddressSanitizer</h1>
 <ul> 
   <li> <a href="intro">Introduction</a>
+  <li> <a href="howtobuild">How to Build</a>
   <li> <a href="usage">Usage</a>
     <ul><li> <a href="has_feature">__has_feature(address_sanitizer)</a></ul>
   <li> <a href="platforms">Supported Platforms</a>
   <li> <a href="limitations">Limitations</a>
   <li> <a href="status">Current Status</a>
+  <li> <a href="moreinfo">More Information</a>
 </ul>
 
 <h2 id="intro">Introduction</h2>
 AddressSanitizer is a fast memory error detector.
 It consists of a compiler instrumentation module and a run-time library.
 The tool can detect the following types of bugs:
-<ul> <li> Out-of-bounds accesses to  <ul><li>heap <li>stack <li>globals</ul>
+<ul> <li> Out-of-bounds accesses to  heap, stack and globals
   <li> Use-after-free
   <li> Use-after-return (to some extent)
-  <li> Double-free
+  <li> Double-free, invalid free
 </ul>
 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>.
+
 <h2 id="intro">Usage</h2>
-In order to use AddressSanitizer simply compile and link your program with
-<tt>-faddress-sanitizer</tt> flag.
-To get a reasonable performance add <tt>-O1</tt> or higher.
-If a bug is detected, the program will print an error message and exit with a
+Simply compile and link your program with <tt>-faddress-sanitizer</tt> flag. <BR>
+To get a reasonable performance add <tt>-O1</tt> or higher. <BR>
+
+<pre>
+% cat example_UseAfterFree.cc
+int main(int argc, char **argv) {
+  int *array = new int[100];
+  delete [] array;
+  return array[argc];  // BOOM
+}
+</pre>
+
+<pre>
+% clang -O1 -g -faddress-sanitizer example_UseAfterFree.cc
+</pre>
+
+If a bug is detected, the program will print an error message to stderr and exit with a
 non-zero exit code.
+Currently, AddressSanitizer does not symbolize its output, so you may need to use a
+separate script to symbolize the result offline (this will be fixed in future).
+<pre>
+% ./a.out 2> log
+% projects/compiler-rt/lib/asan/scripts/asan_symbolize.py / < log | c++filt
+==9442== ERROR: AddressSanitizer heap-use-after-free on address 0x7f7ddab8c084 at pc 0x403c8c bp 0x7fff87fb82d0 sp 0x7fff87fb82c8
+READ of size 4 at 0x7f7ddab8c084 thread T0
+    #0 0x403c8c in main example_UseAfterFree.cc:4
+    #1 0x7f7ddabcac4d in __libc_start_main ??:0
+0x7f7ddab8c084 is located 4 bytes inside of 400-byte region [0x7f7ddab8c080,0x7f7ddab8c210)
+freed by thread T0 here:
+    #0 0x404704 in operator delete[](void*) ??:0
+    #1 0x403c53 in main example_UseAfterFree.cc:4
+    #2 0x7f7ddabcac4d in __libc_start_main ??:0
+previously allocated by thread T0 here:
+    #0 0x404544 in operator new[](unsigned long) ??:0
+    #1 0x403c43 in main example_UseAfterFree.cc:2
+    #2 0x7f7ddabcac4d in __libc_start_main ??:0
+==9442== ABORTING
+</pre>
 
 <h3 id="has_feature">__has_feature(address_sanitizer)</h3>
 In some cases one may need to execute different code depending on whether
@@ -61,10 +99,11 @@ can be used for this purpose.
 </pre>
 
 <h2 id="platforms">Supported Platforms</h2>
-AddressSanitizer is supported on the following platforms:
-<ul> <li>Linux <ul> <li> i386 <li> x86_64 <li> ARM </ul>
-     <li>Darwin <ul> <li> i386 <li> x86_64 </ul>
+AddressSanitizer is supported on
+<ul><li>Linux x86_64 (tested on Ubuntu 10.04).
+<li>MacOS 10.6 i386/x86_64.
 </ul>
+Support for Linux i386/ARM and MacOS 10.7 is in progress.
 
 <h2 id="limitations">Limitations</h2>
 <ul>
@@ -79,8 +118,11 @@ AddressSanitizer is supported on the following platforms:
 
 
 <h2 id="status">Current Status</h2>
-AddressSanitizer is work-in-progress and is not yet fully functional in the LLVM/Clang head.
-For the up-to-date usable version and full documentation refer to
+AddressSanitizer is fully functional on supported platforms in LLVM head.
+However, the test suite is not fully integrated yet and we lack the testing
+process (buildbots).
+
+<h2 id="moreinfo">More Information</h2>
 <a href="http://code.google.com/p/address-sanitizer/">http://code.google.com/p/address-sanitizer</a>.