docs/AddressSanitizer.rst

   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. Currently, AddressSanitizer does not symbolize
  65 its output, so you may need to use a separate script to symbolize the result
  66 offline (this will be fixed in future).
  67
  68 .. code-block:: console
  69
  70     % ./a.out 2> log
  71     % projects/compiler-rt/lib/asan/scripts/asan_symbolize.py / < log | c++filt
  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 AddressSanitizer exits on the first detected error. This is by design.
  88 One reason: it makes the generated code smaller and faster (both by
  89 ~5%). Another reason: this makes fixing bugs unavoidable. With Valgrind,
  90 it is often the case that users treat Valgrind warnings as false
  91 positives (which they are not) and don't fix them.
  92
  93 ``__has_feature(address_sanitizer)``
  94 ------------------------------------
  95
  96 In some cases one may need to execute different code depending on whether
  97 AddressSanitizer is enabled.
  98 :ref:`\_\_has\_feature <langext-__has_feature-__has_extension>` can be used for
  99 this purpose.
 100
 101 .. code-block:: c
 102
 103     #if defined(__has_feature)
 104     #  if __has_feature(address_sanitizer)
 105     // code that builds only under AddressSanitizer
 106     #  endif
 107     #endif
 108
 109 ``__attribute__((no_sanitize_address))``
 110 -----------------------------------------------
 111
 112 Some code should not be instrumented by AddressSanitizer. One may use the
 113 function attribute
 114 :ref:`no_sanitize_address <langext-address_sanitizer>`
 115 (or a deprecated synonym `no_address_safety_analysis`)
 116 to disable instrumentation of a particular function. This attribute may not be
 117 supported by other compilers, so we suggest to use it together with
 118 ``__has_feature(address_sanitizer)``.
 119
 120 Initialization order checking
 121 -----------------------------
 122
 123 AddressSanitizer can optionally detect dynamic initialization order problems,
 124 when initialization of globals defined in one translation unit uses
 125 globals defined in another translation unit. To enable this check at runtime,
 126 you should set environment variable
 127 ``ASAN_OPTIONS=check_initialization_order=1``.
 128
 129 Blacklist
 130 ---------
 131
 132 AddressSanitizer supports ``src`` and ``fun`` entity types in
 133 :doc:`SanitizerSpecialCaseList`, that can be used to suppress error reports
 134 in the specified source files or functions. Additionally, AddressSanitizer
 135 introduces ``global`` and ``type`` entity types that can be used to
 136 suppress error reports for out-of-bound access to globals with certain
 137 names and types (you may only specify class or struct types).
 138
 139 You may use an ``init`` category to suppress reports about initialization-order
 140 problems happening in certain source files or with certain global variables.
 141
 142 .. code-block:: bash
 143
 144     # Suppress error reports for code in a file or in a function:
 145     src:bad_file.cpp
 146     # Ignore all functions with names containing MyFooBar:
 147     fun:*MyFooBar*
 148     # Disable out-of-bound checks for global:
 149     global:bad_array
 150     # Disable out-of-bound checks for global instances of a given class ...
 151     type:class.Namespace::BadClassName
 152     # ... or a given struct. Use wildcard to deal with anonymous namespace.
 153     type:struct.Namespace2::*::BadStructName
 154     # Disable initialization-order checks for globals:
 155     global:bad_init_global=init
 156     type:*BadInitClassSubstring*=init
 157     src:bad/init/files/*=init
 158
 159 Memory leak detection
 160 ---------------------
 161
 162 For the experimental memory leak detector in AddressSanitizer, see
 163 :doc:`LeakSanitizer`.
 164
 165 Supported Platforms
 166 ===================
 167
 168 AddressSanitizer is supported on
 169
 170 * Linux i386/x86\_64 (tested on Ubuntu 10.04 and 12.04);
 171 * MacOS 10.6, 10.7 and 10.8 (i386/x86\_64).
 172
 173 Support for Linux ARM (and Android ARM) is in progress (it may work, but
 174 is not guaranteed too).
 175
 176 Limitations
 177 ===========
 178
 179 * AddressSanitizer uses more real memory than a native run. Exact overhead
 180   depends on the allocations sizes. The smaller the allocations you make the
 181   bigger the overhead is.
 182 * AddressSanitizer uses more stack memory. We have seen up to 3x increase.
 183 * On 64-bit platforms AddressSanitizer maps (but not reserves) 16+ Terabytes of
 184   virtual address space. This means that tools like ``ulimit`` may not work as
 185   usually expected.
 186 * Static linking is not supported.
 187
 188 Current Status
 189 ==============
 190
 191 AddressSanitizer is fully functional on supported platforms starting from LLVM
 192 3.1. The test suite is integrated into CMake build and can be run with ``make
 193 check-asan`` command.
 194
 195 More Information
 196 ================
 197
 198 `http://code.google.com/p/address-sanitizer <http://code.google.com/p/address-sanitizer/>`_
 199