1================
2AddressSanitizer
3================
4
5.. contents::
6   :local:
7
8Introduction
9============
10
11AddressSanitizer is a fast memory error detector. It consists of a compiler
12instrumentation module and a run-time library. The tool can detect the
13following 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
21Typical slowdown introduced by AddressSanitizer is **2x**.
22
23How to build
24============
25
26Follow the `clang build instructions <../get_started.html>`_. CMake build is
27supported.
28
29Usage
30=====
31
32Simply compile and link your program with ``-fsanitize=address`` flag.  The
33AddressSanitizer run-time library should be linked to the final executable, so
34make sure to use ``clang`` (not ``ld``) for the final link step.  When linking
35shared libraries, the AddressSanitizer run-time is not linked, so
36``-Wl,-z,defs`` may cause link errors (don't use it with AddressSanitizer).  To
37get a reasonable performance add ``-O1`` or higher.  To get nicer stack traces
38in error messages add ``-fno-omit-frame-pointer``.  To get perfect stack traces
39you 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
54or:
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
63If a bug is detected, the program will print an error message to stderr and
64exit with a non-zero exit code. To make AddressSanitizer symbolize its output
65you need to set the ``ASAN_SYMBOLIZER_PATH`` environment variable to point to
66the ``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
87If that does not work for you (e.g. your process is sandboxed), you can use a
88separate script to symbolize the result offline (online symbolization can be
89force 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
101Note that on OS X you may need to run ``dsymutil`` on your binary to have the
102file\:line info in the AddressSanitizer reports.
103
104AddressSanitizer exits on the first detected error. This is by design.
105One reason: it makes the generated code smaller and faster (both by
106~5%). Another reason: this makes fixing bugs unavoidable. With Valgrind,
107it is often the case that users treat Valgrind warnings as false
108positives (which they are not) and don't fix them.
109
110``__has_feature(address_sanitizer)``
111------------------------------------
112
113In some cases one may need to execute different code depending on whether
114AddressSanitizer is enabled.
115:ref:`\_\_has\_feature <langext-__has_feature-__has_extension>` can be used for
116this 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
129Some code should not be instrumented by AddressSanitizer. One may use the
130function attribute
131:ref:`no_sanitize_address <langext-address_sanitizer>`
132(or a deprecated synonym `no_address_safety_analysis`)
133to disable instrumentation of a particular function. This attribute may not be
134supported by other compilers, so we suggest to use it together with
135``__has_feature(address_sanitizer)``.
136
137Initialization order checking
138-----------------------------
139
140AddressSanitizer can optionally detect dynamic initialization order problems,
141when initialization of globals defined in one translation unit uses
142globals defined in another translation unit. To enable this check at runtime,
143you should set environment variable
144``ASAN_OPTIONS=check_initialization_order=1``.
145
146Blacklist
147---------
148
149AddressSanitizer supports ``src`` and ``fun`` entity types in
150:doc:`SanitizerSpecialCaseList`, that can be used to suppress error reports
151in the specified source files or functions. Additionally, AddressSanitizer
152introduces ``global`` and ``type`` entity types that can be used to
153suppress error reports for out-of-bound access to globals with certain
154names and types (you may only specify class or struct types).
155
156You may use an ``init`` category to suppress reports about initialization-order
157problems 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:Namespace::BadClassName
169    # ... or a given struct. Use wildcard to deal with anonymous namespace.
170    type: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
176Memory leak detection
177---------------------
178
179For the experimental memory leak detector in AddressSanitizer, see
180:doc:`LeakSanitizer`.
181
182Supported Platforms
183===================
184
185AddressSanitizer 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* FreeBSD i386/x86\_64 (tested on FreeBSD 11-current)
191
192Ports to various other platforms are in progress.
193
194Limitations
195===========
196
197* AddressSanitizer uses more real memory than a native run. Exact overhead
198  depends on the allocations sizes. The smaller the allocations you make the
199  bigger the overhead is.
200* AddressSanitizer uses more stack memory. We have seen up to 3x increase.
201* On 64-bit platforms AddressSanitizer maps (but not reserves) 16+ Terabytes of
202  virtual address space. This means that tools like ``ulimit`` may not work as
203  usually expected.
204* Static linking is not supported.
205
206Current Status
207==============
208
209AddressSanitizer is fully functional on supported platforms starting from LLVM
2103.1. The test suite is integrated into CMake build and can be run with ``make
211check-asan`` command.
212
213More Information
214================
215
216`http://code.google.com/p/address-sanitizer <http://code.google.com/p/address-sanitizer/>`_
217
218