summaryrefslogtreecommitdiff
path: root/clang/docs/AddressSanitizer.html
diff options
context:
space:
mode:
Diffstat (limited to 'clang/docs/AddressSanitizer.html')
-rw-r--r--clang/docs/AddressSanitizer.html139
1 files changed, 139 insertions, 0 deletions
diff --git a/clang/docs/AddressSanitizer.html b/clang/docs/AddressSanitizer.html
new file mode 100644
index 0000000..c1dc91b
--- /dev/null
+++ b/clang/docs/AddressSanitizer.html
@@ -0,0 +1,139 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html4/strict.dtd">
+<!-- Material used from: HTML 4.01 specs: http://www.w3.org/TR/html401/ -->
+<html>
+<head>
+ <META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+ <title>AddressSanitizer, a fast memory error detector</title>
+ <link type="text/css" rel="stylesheet" href="../menu.css">
+ <link type="text/css" rel="stylesheet" href="../content.css">
+ <style type="text/css">
+ td {
+ vertical-align: top;
+ }
+ </style>
+</head>
+<body>
+
+<!--#include virtual="../menu.html.incl"-->
+
+<div id="content">
+
+<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 heap, stack and globals
+ <li> Use-after-free
+ <li> Use-after-return (to some extent)
+ <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>. <BR>
+Note: CMake build does not work yet.
+See <a href="http://llvm.org/bugs/show_bug.cgi?id=12272">bug 12272</a>.
+
+<h2 id="usage">Usage</h2>
+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>
+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>).
+
+<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 -fno-omit-frame-pointer 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
+AddressSanitizer is enabled.
+<a href="LanguageExtensions.html#__has_feature_extension">__has_feature</a>
+can be used for this purpose.
+<pre>
+#if defined(__has_feature) &amp;&amp; __has_feature(address_sanitizer)
+ code that runs only under AddressSanitizer
+#else
+ code that does not run under AddressSanitizer
+#endif
+</pre>
+
+<h2 id="platforms">Supported Platforms</h2>
+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
+(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.
+ <li> On 64-bit platforms AddressSanitizer maps (but not reserves)
+ 16+ Terabytes of virtual address space.
+ This means that tools like <tt>ulimit</tt> may not work as usually expected.
+ <li> Static linking is not supported.
+</ul>
+
+
+<h2 id="status">Current Status</h2>
+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>.
+
+
+</div>
+</body>
+</html>