diff options
Diffstat (limited to 'clang/docs/AddressSanitizer.html')
| -rw-r--r-- | clang/docs/AddressSanitizer.html | 139 |
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) && __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> |