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 <ul><li> <a href="#no_address_safety_analysis"> 29 __attribute__((no_address_safety_analysis))</a></ul> 30 <li> <a href="#platforms">Supported Platforms</a> 31 <li> <a href="#limitations">Limitations</a> 32 <li> <a href="#status">Current Status</a> 33 <li> <a href="#moreinfo">More Information</a> 34 </ul> 35 36 <h2 id="intro">Introduction</h2> 37 AddressSanitizer is a fast memory error detector. 38 It consists of a compiler instrumentation module and a run-time library. 39 The tool can detect the following types of bugs: 40 <ul> <li> Out-of-bounds accesses to heap, stack and globals 41 <li> Use-after-free 42 <li> Use-after-return (to some extent) 43 <li> Double-free, invalid free 44 </ul> 45 Typical slowdown introduced by AddressSanitizer is <b>2x</b>. 46 47 <h2 id="howtobuild">How to build</h2> 48 Follow the <a href="../get_started.html">clang build instructions</a>. <BR> 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) 101 # if __has_feature(address_sanitizer) 102 code that builds only under AddressSanitizer 103 # endif 104 #endif 105 </pre> 106 107 <h3 id="no_address_safety_analysis">__attribute__((no_address_safety_analysis))</h3> 108 Some code should not be instrumentated by AddressSanitizer. 109 One may use the function attribute 110 <a href="LanguageExtensions.html#address_sanitizer"> 111 <tt>no_address_safety_analysis</tt></a> 112 to disable instrumentation of a particular function. 113 This attribute may not be supported by other compilers, so we suggest to 114 use it together with <tt>__has_feature(address_sanitizer)</tt>. 115 Note: currently, this attribute will be lost if the function is inlined. 116 117 <h2 id="platforms">Supported Platforms</h2> 118 AddressSanitizer is supported on 119 <ul><li>Linux x86_64 (tested on Ubuntu 10.04). 120 <li>MacOS 10.6, 10.7 and 10.8 (i386/x86_64). 121 </ul> 122 Support for Linux i386/ARM is in progress 123 (it may work, but is not guaranteed too). 124 125 126 <h2 id="limitations">Limitations</h2> 127 <ul> 128 <li> AddressSanitizer uses more real memory than a native run. 129 How much -- depends on the allocations sizes. The smaller the 130 allocations you make the bigger the overhead. 131 <li> AddressSanitizer uses more stack memory. We have seen up to 3x increase. 132 <li> On 64-bit platforms AddressSanitizer maps (but not reserves) 133 16+ Terabytes of virtual address space. 134 This means that tools like <tt>ulimit</tt> may not work as usually expected. 135 <li> Static linking is not supported. 136 </ul> 137 138 139 <h2 id="status">Current Status</h2> 140 AddressSanitizer is fully functional on supported platforms starting from LLVM 3.1. 141 The test suite is integrated into CMake build (can be run with "make 142 check-asan" command). 143 144 <h2 id="moreinfo">More Information</h2> 145 <a href="http://code.google.com/p/address-sanitizer/">http://code.google.com/p/address-sanitizer</a>. 146 147 148 </div> 149 </body> 150 </html> 151
