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
26Build LLVM/Clang with `CMake <http://llvm.org/docs/CMake.html>`_.
27
28Usage
29=====
30
31Simply compile and link your program with ``-fsanitize=address`` flag.  The
32AddressSanitizer run-time library should be linked to the final executable, so
33make sure to use ``clang`` (not ``ld``) for the final link step.  When linking
34shared libraries, the AddressSanitizer run-time is not linked, so
35``-Wl,-z,defs`` may cause link errors (don't use it with AddressSanitizer).  To
36get a reasonable performance add ``-O1`` or higher.  To get nicer stack traces
37in error messages add ``-fno-omit-frame-pointer``.  To get perfect stack traces
38you may need to disable inlining (just use ``-O1``) and tail call elimination
39(``-fno-optimize-sibling-calls``).
40
41.. code-block:: console
42
43    % cat example_UseAfterFree.cc
44    int main(int argc, char **argv) {
45      int *array = new int[100];
46      delete [] array;
47      return array[argc];  // BOOM
48    }
49
50    # Compile and link
51    % clang -O1 -g -fsanitize=address -fno-omit-frame-pointer example_UseAfterFree.cc
52
53or:
54
55.. code-block:: console
56
57    # Compile
58    % clang -O1 -g -fsanitize=address -fno-omit-frame-pointer -c example_UseAfterFree.cc
59    # Link
60    % clang -g -fsanitize=address example_UseAfterFree.o
61
62If a bug is detected, the program will print an error message to stderr and
63exit with a non-zero exit code. AddressSanitizer exits on the first detected error.
64This is by design:
65
66* This approach allows AddressSanitizer to produce faster and smaller generated code
67  (both by ~5%).
68* Fixing bugs becomes unavoidable. AddressSanitizer does not produce
69  false alarms. Once a memory corruption occurs, the program is in an inconsistent
70  state, which could lead to confusing results and potentially misleading
71  subsequent reports.
72
73If your process is sandboxed and you are running on OS X 10.10 or earlier, you
74will need to set ``DYLD_INSERT_LIBRARIES`` environment variable and point it to
75the ASan library that is packaged with the compiler used to build the
76executable. (You can find the library by searching for dynamic libraries with
77``asan`` in their name.) If the environment variable is not set, the process will
78try to re-exec. Also keep in mind that when moving the executable to another machine,
79the ASan library will also need to be copied over.
80
81Symbolizing the Reports
82=========================
83
84To make AddressSanitizer symbolize its output
85you need to set the ``ASAN_SYMBOLIZER_PATH`` environment variable to point to
86the ``llvm-symbolizer`` binary (or make sure ``llvm-symbolizer`` is in your
87``$PATH``):
88
89.. code-block:: console
90
91    % ASAN_SYMBOLIZER_PATH=/usr/local/bin/llvm-symbolizer ./a.out
92    ==9442== ERROR: AddressSanitizer heap-use-after-free on address 0x7f7ddab8c084 at pc 0x403c8c bp 0x7fff87fb82d0 sp 0x7fff87fb82c8
93    READ of size 4 at 0x7f7ddab8c084 thread T0
94        #0 0x403c8c in main example_UseAfterFree.cc:4
95        #1 0x7f7ddabcac4d in __libc_start_main ??:0
96    0x7f7ddab8c084 is located 4 bytes inside of 400-byte region [0x7f7ddab8c080,0x7f7ddab8c210)
97    freed by thread T0 here:
98        #0 0x404704 in operator delete[](void*) ??:0
99        #1 0x403c53 in main example_UseAfterFree.cc:4
100        #2 0x7f7ddabcac4d in __libc_start_main ??:0
101    previously allocated by thread T0 here:
102        #0 0x404544 in operator new[](unsigned long) ??:0
103        #1 0x403c43 in main example_UseAfterFree.cc:2
104        #2 0x7f7ddabcac4d in __libc_start_main ??:0
105    ==9442== ABORTING
106
107If that does not work for you (e.g. your process is sandboxed), you can use a
108separate script to symbolize the result offline (online symbolization can be
109force disabled by setting ``ASAN_OPTIONS=symbolize=0``):
110
111.. code-block:: console
112
113    % ASAN_OPTIONS=symbolize=0 ./a.out 2> log
114    % projects/compiler-rt/lib/asan/scripts/asan_symbolize.py / < log | c++filt
115    ==9442== ERROR: AddressSanitizer heap-use-after-free on address 0x7f7ddab8c084 at pc 0x403c8c bp 0x7fff87fb82d0 sp 0x7fff87fb82c8
116    READ of size 4 at 0x7f7ddab8c084 thread T0
117        #0 0x403c8c in main example_UseAfterFree.cc:4
118        #1 0x7f7ddabcac4d in __libc_start_main ??:0
119    ...
120
121Note that on OS X you may need to run ``dsymutil`` on your binary to have the
122file\:line info in the AddressSanitizer reports.
123
124Additional Checks
125=================
126
127Initialization order checking
128-----------------------------
129
130AddressSanitizer can optionally detect dynamic initialization order problems,
131when initialization of globals defined in one translation unit uses
132globals defined in another translation unit. To enable this check at runtime,
133you should set environment variable
134``ASAN_OPTIONS=check_initialization_order=1``.
135
136Note that this option is not supported on OS X.
137
138Memory leak detection
139---------------------
140
141For more information on leak detector in AddressSanitizer, see
142:doc:`LeakSanitizer`. The leak detection is turned on by default on Linux;
143however, it is not yet supported on other platforms.
144
145Issue Suppression
146=================
147
148AddressSanitizer is not expected to produce false positives. If you see one,
149look again; most likely it is a true positive!
150
151Suppressing Reports in External Libraries
152-----------------------------------------
153Runtime interposition allows AddressSanitizer to find bugs in code that is
154not being recompiled. If you run into an issue in external libraries, we
155recommend immediately reporting it to the library maintainer so that it
156gets addressed. However, you can use the following suppression mechanism
157to unblock yourself and continue on with the testing. This suppression
158mechanism should only be used for suppressing issues in external code; it
159does not work on code recompiled with AddressSanitizer. To suppress errors
160in external libraries, set the ``ASAN_OPTIONS`` environment variable to point
161to a suppression file. You can either specify the full path to the file or the
162path of the file relative to the location of your executable.
163
164.. code-block:: bash
165
166    ASAN_OPTIONS=suppressions=MyASan.supp
167
168Use the following format to specify the names of the functions or libraries
169you want to suppress. You can see these in the error report. Remember that
170the narrower the scope of the suppression, the more bugs you will be able to
171catch.
172
173.. code-block:: bash
174
175    interceptor_via_fun:NameOfCFunctionToSuppress
176    interceptor_via_fun:-[ClassName objCMethodToSuppress:]
177    interceptor_via_lib:NameOfTheLibraryToSuppress
178
179Conditional Compilation with ``__has_feature(address_sanitizer)``
180-----------------------------------------------------------------
181
182In some cases one may need to execute different code depending on whether
183AddressSanitizer is enabled.
184:ref:`\_\_has\_feature <langext-__has_feature-__has_extension>` can be used for
185this purpose.
186
187.. code-block:: c
188
189    #if defined(__has_feature)
190    #  if __has_feature(address_sanitizer)
191    // code that builds only under AddressSanitizer
192    #  endif
193    #endif
194
195Disabling Instrumentation with ``__attribute__((no_sanitize("address")))``
196--------------------------------------------------------------------------
197
198Some code should not be instrumented by AddressSanitizer. One may use the
199function attribute ``__attribute__((no_sanitize("address")))`` (which has
200deprecated synonyms `no_sanitize_address` and `no_address_safety_analysis`) to
201disable instrumentation of a particular function. This attribute may not be
202supported by other compilers, so we suggest to use it together with
203``__has_feature(address_sanitizer)``.
204
205Suppressing Errors in Recompiled Code (Blacklist)
206-------------------------------------------------
207
208AddressSanitizer supports ``src`` and ``fun`` entity types in
209:doc:`SanitizerSpecialCaseList`, that can be used to suppress error reports
210in the specified source files or functions. Additionally, AddressSanitizer
211introduces ``global`` and ``type`` entity types that can be used to
212suppress error reports for out-of-bound access to globals with certain
213names and types (you may only specify class or struct types).
214
215You may use an ``init`` category to suppress reports about initialization-order
216problems happening in certain source files or with certain global variables.
217
218.. code-block:: bash
219
220    # Suppress error reports for code in a file or in a function:
221    src:bad_file.cpp
222    # Ignore all functions with names containing MyFooBar:
223    fun:*MyFooBar*
224    # Disable out-of-bound checks for global:
225    global:bad_array
226    # Disable out-of-bound checks for global instances of a given class ...
227    type:Namespace::BadClassName
228    # ... or a given struct. Use wildcard to deal with anonymous namespace.
229    type:Namespace2::*::BadStructName
230    # Disable initialization-order checks for globals:
231    global:bad_init_global=init
232    type:*BadInitClassSubstring*=init
233    src:bad/init/files/*=init
234
235Suppressing memory leaks
236------------------------
237
238Memory leak reports produced by :doc:`LeakSanitizer` (if it is run as a part
239of AddressSanitizer) can be suppressed by a separate file passed as
240
241.. code-block:: bash
242
243    LSAN_OPTIONS=suppressions=MyLSan.supp
244
245which contains lines of the form `leak:<pattern>`. Memory leak will be
246suppressed if pattern matches any function name, source file name, or
247library name in the symbolized stack trace of the leak report. See
248`full documentation
249<https://github.com/google/sanitizers/wiki/AddressSanitizerLeakSanitizer#suppressions>`_
250for more details.
251
252Limitations
253===========
254
255* AddressSanitizer uses more real memory than a native run. Exact overhead
256  depends on the allocations sizes. The smaller the allocations you make the
257  bigger the overhead is.
258* AddressSanitizer uses more stack memory. We have seen up to 3x increase.
259* On 64-bit platforms AddressSanitizer maps (but not reserves) 16+ Terabytes of
260  virtual address space. This means that tools like ``ulimit`` may not work as
261  usually expected.
262* Static linking is not supported.
263
264Supported Platforms
265===================
266
267AddressSanitizer is supported on:
268
269* Linux i386/x86\_64 (tested on Ubuntu 12.04)
270* OS X 10.7 - 10.11 (i386/x86\_64)
271* iOS Simulator
272* Android ARM
273* FreeBSD i386/x86\_64 (tested on FreeBSD 11-current)
274
275Ports to various other platforms are in progress.
276
277Current Status
278==============
279
280AddressSanitizer is fully functional on supported platforms starting from LLVM
2813.1. The test suite is integrated into CMake build and can be run with ``make
282check-asan`` command.
283
284More Information
285================
286
287`<https://github.com/google/sanitizers/wiki/AddressSanitizer>`_
288