| <!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> |
| <ul><li> <a href="#no_address_safety_analysis"> |
| __attribute__((no_address_safety_analysis))</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> |
| |
| <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) |
| # if __has_feature(address_sanitizer) |
| code that builds only under AddressSanitizer |
| # endif |
| #endif |
| </pre> |
| |
| <h3 id="no_address_safety_analysis">__attribute__((no_address_safety_analysis))</h3> |
| Some code should not be instrumentated by AddressSanitizer. |
| One may use the function attribute |
| <a href="LanguageExtensions.html#address_sanitizer"> |
| <tt>no_address_safety_analysis</tt></a> |
| to disable instrumentation of a particular function. |
| This attribute may not be supported by other compilers, so we suggest to |
| use it together with <tt>__has_feature(address_sanitizer)</tt>. |
| Note: currently, this attribute will be lost if the function is inlined. |
| |
| <h2 id="platforms">Supported Platforms</h2> |
| AddressSanitizer is supported on |
| <ul><li>Linux x86_64 (tested on Ubuntu 10.04). |
| <li>MacOS 10.6, 10.7 and 10.8 (i386/x86_64). |
| </ul> |
| Support for Linux i386/ARM 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> AddressSanitizer uses more stack memory. We have seen up to 3x increase. |
| <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 starting from LLVM 3.1. |
| The test suite is integrated into CMake build (can be run with "make |
| check-asan" command). |
| |
| <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> |