1 ================ 2 AddressSanitizer 3 ================ 4 5 .. contents:: 6 :local: 7 8 Introduction 9 ============ 10 11 AddressSanitizer is a fast memory error detector. It consists of a compiler 12 instrumentation module and a run-time library. The tool can detect the 13 following types of bugs: 14 15 * Out-of-bounds accesses to heap, stack and globals 16 * Use-after-free 17 * Use-after-return (to some extent) 18 * Double-free, invalid free 19 * Memory leaks (experimental) 20 21 Typical slowdown introduced by AddressSanitizer is **2x**. 22 23 How to build 24 ============ 25 26 Follow the `clang build instructions <../get_started.html>`_. CMake build is 27 supported. 28 29 Usage 30 ===== 31 32 Simply compile and link your program with ``-fsanitize=address`` flag. The 33 AddressSanitizer run-time library should be linked to the final executable, so 34 make sure to use ``clang`` (not ``ld``) for the final link step. When linking 35 shared libraries, the AddressSanitizer run-time is not linked, so 36 ``-Wl,-z,defs`` may cause link errors (don't use it with AddressSanitizer). To 37 get a reasonable performance add ``-O1`` or higher. To get nicer stack traces 38 in error messages add ``-fno-omit-frame-pointer``. To get perfect stack traces 39 you may need to disable inlining (just use ``-O1``) and tail call elimination 40 (``-fno-optimize-sibling-calls``). 41 42 .. code-block:: console 43 44 % cat example_UseAfterFree.cc 45 int main(int argc, char **argv) { 46 int *array = new int[100]; 47 delete [] array; 48 return array[argc]; // BOOM 49 } 50 51 # Compile and link 52 % clang -O1 -g -fsanitize=address -fno-omit-frame-pointer example_UseAfterFree.cc 53 54 or: 55 56 .. code-block:: console 57 58 # Compile 59 % clang -O1 -g -fsanitize=address -fno-omit-frame-pointer -c example_UseAfterFree.cc 60 # Link 61 % clang -g -fsanitize=address example_UseAfterFree.o 62 63 If a bug is detected, the program will print an error message to stderr and 64 exit with a non-zero exit code. To make AddressSanitizer symbolize its output 65 you need to set the ``ASAN_SYMBOLIZER_PATH`` environment variable to point to 66 the ``llvm-symbolizer`` binary (or make sure ``llvm-symbolizer`` is in your 67 ``$PATH``): 68 69 .. code-block:: console 70 71 % ASAN_SYMBOLIZER_PATH=/usr/local/bin/llvm-symbolizer ./a.out 72 ==9442== ERROR: AddressSanitizer heap-use-after-free on address 0x7f7ddab8c084 at pc 0x403c8c bp 0x7fff87fb82d0 sp 0x7fff87fb82c8 73 READ of size 4 at 0x7f7ddab8c084 thread T0 74 #0 0x403c8c in main example_UseAfterFree.cc:4 75 #1 0x7f7ddabcac4d in __libc_start_main ??:0 76 0x7f7ddab8c084 is located 4 bytes inside of 400-byte region [0x7f7ddab8c080,0x7f7ddab8c210) 77 freed by thread T0 here: 78 #0 0x404704 in operator delete[](void*) ??:0 79 #1 0x403c53 in main example_UseAfterFree.cc:4 80 #2 0x7f7ddabcac4d in __libc_start_main ??:0 81 previously allocated by thread T0 here: 82 #0 0x404544 in operator new[](unsigned long) ??:0 83 #1 0x403c43 in main example_UseAfterFree.cc:2 84 #2 0x7f7ddabcac4d in __libc_start_main ??:0 85 ==9442== ABORTING 86 87 If that does not work for you (e.g. your process is sandboxed), you can use a 88 separate script to symbolize the result offline (online symbolization can be 89 force disabled by setting ``ASAN_OPTIONS=symbolize=0``): 90 91 .. code-block:: console 92 93 % ASAN_OPTIONS=symbolize=0 ./a.out 2> log 94 % projects/compiler-rt/lib/asan/scripts/asan_symbolize.py / < log | c++filt 95 ==9442== ERROR: AddressSanitizer heap-use-after-free on address 0x7f7ddab8c084 at pc 0x403c8c bp 0x7fff87fb82d0 sp 0x7fff87fb82c8 96 READ of size 4 at 0x7f7ddab8c084 thread T0 97 #0 0x403c8c in main example_UseAfterFree.cc:4 98 #1 0x7f7ddabcac4d in __libc_start_main ??:0 99 ... 100 101 Note that on OS X you may need to run ``dsymutil`` on your binary to have the 102 file\:line info in the AddressSanitizer reports. 103 104 AddressSanitizer exits on the first detected error. This is by design. 105 One reason: it makes the generated code smaller and faster (both by 106 ~5%). Another reason: this makes fixing bugs unavoidable. With Valgrind, 107 it is often the case that users treat Valgrind warnings as false 108 positives (which they are not) and don't fix them. 109 110 ``__has_feature(address_sanitizer)`` 111 ------------------------------------ 112 113 In some cases one may need to execute different code depending on whether 114 AddressSanitizer is enabled. 115 :ref:`\_\_has\_feature <langext-__has_feature-__has_extension>` can be used for 116 this purpose. 117 118 .. code-block:: c 119 120 #if defined(__has_feature) 121 # if __has_feature(address_sanitizer) 122 // code that builds only under AddressSanitizer 123 # endif 124 #endif 125 126 ``__attribute__((no_sanitize_address))`` 127 ----------------------------------------------- 128 129 Some code should not be instrumented by AddressSanitizer. One may use the 130 function attribute 131 :ref:`no_sanitize_address <langext-address_sanitizer>` 132 (or a deprecated synonym `no_address_safety_analysis`) 133 to disable instrumentation of a particular function. This attribute may not be 134 supported by other compilers, so we suggest to use it together with 135 ``__has_feature(address_sanitizer)``. 136 137 Initialization order checking 138 ----------------------------- 139 140 AddressSanitizer can optionally detect dynamic initialization order problems, 141 when initialization of globals defined in one translation unit uses 142 globals defined in another translation unit. To enable this check at runtime, 143 you should set environment variable 144 ``ASAN_OPTIONS=check_initialization_order=1``. 145 146 Blacklist 147 --------- 148 149 AddressSanitizer supports ``src`` and ``fun`` entity types in 150 :doc:`SanitizerSpecialCaseList`, that can be used to suppress error reports 151 in the specified source files or functions. Additionally, AddressSanitizer 152 introduces ``global`` and ``type`` entity types that can be used to 153 suppress error reports for out-of-bound access to globals with certain 154 names and types (you may only specify class or struct types). 155 156 You may use an ``init`` category to suppress reports about initialization-order 157 problems happening in certain source files or with certain global variables. 158 159 .. code-block:: bash 160 161 # Suppress error reports for code in a file or in a function: 162 src:bad_file.cpp 163 # Ignore all functions with names containing MyFooBar: 164 fun:*MyFooBar* 165 # Disable out-of-bound checks for global: 166 global:bad_array 167 # Disable out-of-bound checks for global instances of a given class ... 168 type:class.Namespace::BadClassName 169 # ... or a given struct. Use wildcard to deal with anonymous namespace. 170 type:struct.Namespace2::*::BadStructName 171 # Disable initialization-order checks for globals: 172 global:bad_init_global=init 173 type:*BadInitClassSubstring*=init 174 src:bad/init/files/*=init 175 176 Memory leak detection 177 --------------------- 178 179 For the experimental memory leak detector in AddressSanitizer, see 180 :doc:`LeakSanitizer`. 181 182 Supported Platforms 183 =================== 184 185 AddressSanitizer is supported on 186 187 * Linux i386/x86\_64 (tested on Ubuntu 12.04); 188 * MacOS 10.6 - 10.9 (i386/x86\_64). 189 * Android ARM 190 191 Ports to various other platforms are in progress. 192 193 Limitations 194 =========== 195 196 * AddressSanitizer uses more real memory than a native run. Exact overhead 197 depends on the allocations sizes. The smaller the allocations you make the 198 bigger the overhead is. 199 * AddressSanitizer uses more stack memory. We have seen up to 3x increase. 200 * On 64-bit platforms AddressSanitizer maps (but not reserves) 16+ Terabytes of 201 virtual address space. This means that tools like ``ulimit`` may not work as 202 usually expected. 203 * Static linking is not supported. 204 205 Current Status 206 ============== 207 208 AddressSanitizer is fully functional on supported platforms starting from LLVM 209 3.1. The test suite is integrated into CMake build and can be run with ``make 210 check-asan`` command. 211 212 More Information 213 ================ 214 215 `http://code.google.com/p/address-sanitizer <http://code.google.com/p/address-sanitizer/>`_ 216 217
