1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" 2 "http://www.w3.org/TR/html4/strict.dtd"> 3 <!-- Material used from: HTML 4.01 specs: http://www.w3.org/TR/html401/ --> 4 <html> 5 <head> 6 <META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> 7 <title>AddressSanitizer, a fast memory error detector</title> 8 <link type="text/css" rel="stylesheet" href="../menu.css"> 9 <link type="text/css" rel="stylesheet" href="../content.css"> 10 <style type="text/css"> 11 td { 12 vertical-align: top; 13 } 14 </style> 15 </head> 16 <body> 17 18 <!--#include virtual="../menu.html.incl"--> 19 20 <div id="content"> 21 22 <h1>AddressSanitizer</h1> 23 <ul> 24 <li> <a href="intro">Introduction</a> 25 <li> <a href="howtobuild">How to Build</a> 26 <li> <a href="usage">Usage</a> 27 <ul><li> <a href="has_feature">__has_feature(address_sanitizer)</a></ul> 28 <li> <a href="platforms">Supported Platforms</a> 29 <li> <a href="limitations">Limitations</a> 30 <li> <a href="status">Current Status</a> 31 <li> <a href="moreinfo">More Information</a> 32 </ul> 33 34 <h2 id="intro">Introduction</h2> 35 AddressSanitizer is a fast memory error detector. 36 It consists of a compiler instrumentation module and a run-time library. 37 The tool can detect the following types of bugs: 38 <ul> <li> Out-of-bounds accesses to heap, stack and globals 39 <li> Use-after-free 40 <li> Use-after-return (to some extent) 41 <li> Double-free, invalid free 42 </ul> 43 Typical slowdown introduced by AddressSanitizer is <b>2x</b>. 44 45 <h2 id="howtobuild">How to build</h2> 46 Follow the <a href="../get_started.html">clang build instructions</a>. <BR> 47 Note: CMake build does not work yet. 48 See <a href="http://llvm.org/bugs/show_bug.cgi?id=12272">bug 12272</a>. 49 50 <h2 id="usage">Usage</h2> 51 Simply compile and link your program with <tt>-faddress-sanitizer</tt> flag. <BR> 52 To get a reasonable performance add <tt>-O1</tt> or higher. <BR> 53 To get nicer stack traces in error messages add 54 <tt>-fno-omit-frame-pointer</tt>. <BR> 55 To get perfect stack traces you may need to disable inlining (just use <tt>-O1</tt>) and tail call 56 elimination (</tt>-fno-optimize-sibling-calls</tt>). 57 58 <pre> 59 % cat example_UseAfterFree.cc 60 int main(int argc, char **argv) { 61 int *array = new int[100]; 62 delete [] array; 63 return array[argc]; // BOOM 64 } 65 </pre> 66 67 <pre> 68 % clang -O1 -g -faddress-sanitizer -fno-omit-frame-pointer example_UseAfterFree.cc 69 </pre> 70 71 If a bug is detected, the program will print an error message to stderr and exit with a 72 non-zero exit code. 73 Currently, AddressSanitizer does not symbolize its output, so you may need to use a 74 separate script to symbolize the result offline (this will be fixed in future). 75 <pre> 76 % ./a.out 2> log 77 % projects/compiler-rt/lib/asan/scripts/asan_symbolize.py / < log | c++filt 78 ==9442== ERROR: AddressSanitizer heap-use-after-free on address 0x7f7ddab8c084 at pc 0x403c8c bp 0x7fff87fb82d0 sp 0x7fff87fb82c8 79 READ of size 4 at 0x7f7ddab8c084 thread T0 80 #0 0x403c8c in main example_UseAfterFree.cc:4 81 #1 0x7f7ddabcac4d in __libc_start_main ??:0 82 0x7f7ddab8c084 is located 4 bytes inside of 400-byte region [0x7f7ddab8c080,0x7f7ddab8c210) 83 freed by thread T0 here: 84 #0 0x404704 in operator delete[](void*) ??:0 85 #1 0x403c53 in main example_UseAfterFree.cc:4 86 #2 0x7f7ddabcac4d in __libc_start_main ??:0 87 previously allocated by thread T0 here: 88 #0 0x404544 in operator new[](unsigned long) ??:0 89 #1 0x403c43 in main example_UseAfterFree.cc:2 90 #2 0x7f7ddabcac4d in __libc_start_main ??:0 91 ==9442== ABORTING 92 </pre> 93 94 <h3 id="has_feature">__has_feature(address_sanitizer)</h3> 95 In some cases one may need to execute different code depending on whether 96 AddressSanitizer is enabled. 97 <a href="LanguageExtensions.html#__has_feature_extension">__has_feature</a> 98 can be used for this purpose. 99 <pre> 100 #if defined(__has_feature) && __has_feature(address_sanitizer) 101 code that runs only under AddressSanitizer 102 #else 103 code that does not run under AddressSanitizer 104 #endif 105 </pre> 106 107 <h2 id="platforms">Supported Platforms</h2> 108 AddressSanitizer is supported on 109 <ul><li>Linux x86_64 (tested on Ubuntu 10.04). 110 <li>MacOS 10.6 i386/x86_64. 111 </ul> 112 Support for Linux i386/ARM and MacOS 10.7 is in progress 113 (it may work, but is not guaranteed too). 114 115 116 <h2 id="limitations">Limitations</h2> 117 <ul> 118 <li> AddressSanitizer uses more real memory than a native run. 119 How much -- depends on the allocations sizes. The smaller the 120 allocations you make the bigger the overhead. 121 <li> On 64-bit platforms AddressSanitizer maps (but not reserves) 122 16+ Terabytes of virtual address space. 123 This means that tools like <tt>ulimit</tt> may not work as usually expected. 124 <li> Static linking is not supported. 125 </ul> 126 127 128 <h2 id="status">Current Status</h2> 129 AddressSanitizer is fully functional on supported platforms in LLVM head. 130 However, the test suite is not fully integrated yet and we lack the testing 131 process (buildbots). 132 133 <h2 id="moreinfo">More Information</h2> 134 <a href="http://code.google.com/p/address-sanitizer/">http://code.google.com/p/address-sanitizer</a>. 135 136 137 </div> 138 </body> 139 </html> 140
