AddressSanitizer

• Introduction
• How to Build
• Usage
  • __has_feature(address_sanitizer)
  • __attribute__((no_address_safety_analysis))
• Supported Platforms
• Limitations
• Current Status
• More Information

Introduction

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:

• Out-of-bounds accesses to heap, stack and globals
• Use-after-free
• Use-after-return (to some extent)
• Double-free, invalid free

Typical slowdown introduced by AddressSanitizer is 2x.

How to build

Follow the clang build instructions.
Note: CMake build does not work yet. See bug 12272.

Usage

Simply compile and link your program with -faddress-sanitizer flag.
To get a reasonable performance add -O1 or higher.
To get nicer stack traces in error messages add -fno-omit-frame-pointer.
To get perfect stack traces you may need to disable inlining (just use -O1) and tail call elimination (-fno-optimize-sibling-calls).

% cat example_UseAfterFree.cc
int main(int argc, char **argv) {
  int *array = new int[100];
  delete [] array;
  return array[argc];  // BOOM
}

% clang -O1 -g -faddress-sanitizer -fno-omit-frame-pointer example_UseAfterFree.cc

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).

% ./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

__has_feature(address_sanitizer)

In some cases one may need to execute different code depending on whether AddressSanitizer is enabled. __has_feature can be used for this purpose.

#if defined(__has_feature)
# if __has_feature(address_sanitizer)
  code that builds only under AddressSanitizer
# endif
#endif

__attribute__((no_address_safety_analysis))

Some code should not be instrumentated by AddressSanitizer. One may use the function attribute no_address_safety_analysis to disable instrumentation of a particular function. This attribute may not be supported by other compilers, so we suggest to use it together with __has_feature(address_sanitizer). Note: currently, this attribute will be lost if the function is inlined.

Supported Platforms

AddressSanitizer is supported on

• Linux x86_64 (tested on Ubuntu 10.04).
• MacOS 10.6 and 10.7 (i386/x86_64).

Support for Linux i386/ARM is in progress (it may work, but is not guaranteed too).

Limitations

• 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.
• AddressSanitizer uses more stack memory. We have seen up to 3x increase.
• On 64-bit platforms AddressSanitizer maps (but not reserves) 16+ Terabytes of virtual address space. This means that tools like ulimit may not work as usually expected.
• Static linking is not supported.

Current Status

AddressSanitizer is fully functional on supported platforms starting from LLVM 3.1. However, the test suite is not fully integrated yet and we lack the testing process (buildbots).

More Information

http://code.google.com/p/address-sanitizer.