1e5dd7070Spatrick================ 2e5dd7070SpatrickAddressSanitizer 3e5dd7070Spatrick================ 4e5dd7070Spatrick 5e5dd7070Spatrick.. contents:: 6e5dd7070Spatrick :local: 7e5dd7070Spatrick 8e5dd7070SpatrickIntroduction 9e5dd7070Spatrick============ 10e5dd7070Spatrick 11e5dd7070SpatrickAddressSanitizer is a fast memory error detector. It consists of a compiler 12e5dd7070Spatrickinstrumentation module and a run-time library. The tool can detect the 13e5dd7070Spatrickfollowing types of bugs: 14e5dd7070Spatrick 15e5dd7070Spatrick* Out-of-bounds accesses to heap, stack and globals 16e5dd7070Spatrick* Use-after-free 17a9ac8606Spatrick* Use-after-return (clang flag ``-fsanitize-address-use-after-return=(never|runtime|always)`` default: ``runtime``) 18*12c85518Srobert * Enable with: ``ASAN_OPTIONS=detect_stack_use_after_return=1`` (already enabled on Linux). 19*12c85518Srobert * Disable with: ``ASAN_OPTIONS=detect_stack_use_after_return=0``. 20a9ac8606Spatrick* Use-after-scope (clang flag ``-fsanitize-address-use-after-scope``) 21e5dd7070Spatrick* Double-free, invalid free 22e5dd7070Spatrick* Memory leaks (experimental) 23e5dd7070Spatrick 24e5dd7070SpatrickTypical slowdown introduced by AddressSanitizer is **2x**. 25e5dd7070Spatrick 26e5dd7070SpatrickHow to build 27e5dd7070Spatrick============ 28e5dd7070Spatrick 29e5dd7070SpatrickBuild LLVM/Clang with `CMake <https://llvm.org/docs/CMake.html>`_. 30e5dd7070Spatrick 31e5dd7070SpatrickUsage 32e5dd7070Spatrick===== 33e5dd7070Spatrick 34e5dd7070SpatrickSimply compile and link your program with ``-fsanitize=address`` flag. The 35e5dd7070SpatrickAddressSanitizer run-time library should be linked to the final executable, so 36e5dd7070Spatrickmake sure to use ``clang`` (not ``ld``) for the final link step. When linking 37e5dd7070Spatrickshared libraries, the AddressSanitizer run-time is not linked, so 38e5dd7070Spatrick``-Wl,-z,defs`` may cause link errors (don't use it with AddressSanitizer). To 39e5dd7070Spatrickget a reasonable performance add ``-O1`` or higher. To get nicer stack traces 40e5dd7070Spatrickin error messages add ``-fno-omit-frame-pointer``. To get perfect stack traces 41e5dd7070Spatrickyou may need to disable inlining (just use ``-O1``) and tail call elimination 42e5dd7070Spatrick(``-fno-optimize-sibling-calls``). 43e5dd7070Spatrick 44e5dd7070Spatrick.. code-block:: console 45e5dd7070Spatrick 46e5dd7070Spatrick % cat example_UseAfterFree.cc 47e5dd7070Spatrick int main(int argc, char **argv) { 48e5dd7070Spatrick int *array = new int[100]; 49e5dd7070Spatrick delete [] array; 50e5dd7070Spatrick return array[argc]; // BOOM 51e5dd7070Spatrick } 52e5dd7070Spatrick 53e5dd7070Spatrick # Compile and link 54e5dd7070Spatrick % clang++ -O1 -g -fsanitize=address -fno-omit-frame-pointer example_UseAfterFree.cc 55e5dd7070Spatrick 56e5dd7070Spatrickor: 57e5dd7070Spatrick 58e5dd7070Spatrick.. code-block:: console 59e5dd7070Spatrick 60e5dd7070Spatrick # Compile 61e5dd7070Spatrick % clang++ -O1 -g -fsanitize=address -fno-omit-frame-pointer -c example_UseAfterFree.cc 62e5dd7070Spatrick # Link 63e5dd7070Spatrick % clang++ -g -fsanitize=address example_UseAfterFree.o 64e5dd7070Spatrick 65e5dd7070SpatrickIf a bug is detected, the program will print an error message to stderr and 66e5dd7070Spatrickexit with a non-zero exit code. AddressSanitizer exits on the first detected error. 67e5dd7070SpatrickThis is by design: 68e5dd7070Spatrick 69e5dd7070Spatrick* This approach allows AddressSanitizer to produce faster and smaller generated code 70e5dd7070Spatrick (both by ~5%). 71e5dd7070Spatrick* Fixing bugs becomes unavoidable. AddressSanitizer does not produce 72e5dd7070Spatrick false alarms. Once a memory corruption occurs, the program is in an inconsistent 73e5dd7070Spatrick state, which could lead to confusing results and potentially misleading 74e5dd7070Spatrick subsequent reports. 75e5dd7070Spatrick 76e5dd7070SpatrickIf your process is sandboxed and you are running on OS X 10.10 or earlier, you 77e5dd7070Spatrickwill need to set ``DYLD_INSERT_LIBRARIES`` environment variable and point it to 78e5dd7070Spatrickthe ASan library that is packaged with the compiler used to build the 79e5dd7070Spatrickexecutable. (You can find the library by searching for dynamic libraries with 80e5dd7070Spatrick``asan`` in their name.) If the environment variable is not set, the process will 81e5dd7070Spatricktry to re-exec. Also keep in mind that when moving the executable to another machine, 82e5dd7070Spatrickthe ASan library will also need to be copied over. 83e5dd7070Spatrick 84e5dd7070SpatrickSymbolizing the Reports 85e5dd7070Spatrick========================= 86e5dd7070Spatrick 87e5dd7070SpatrickTo make AddressSanitizer symbolize its output 88e5dd7070Spatrickyou need to set the ``ASAN_SYMBOLIZER_PATH`` environment variable to point to 89e5dd7070Spatrickthe ``llvm-symbolizer`` binary (or make sure ``llvm-symbolizer`` is in your 90e5dd7070Spatrick``$PATH``): 91e5dd7070Spatrick 92e5dd7070Spatrick.. code-block:: console 93e5dd7070Spatrick 94e5dd7070Spatrick % ASAN_SYMBOLIZER_PATH=/usr/local/bin/llvm-symbolizer ./a.out 95e5dd7070Spatrick ==9442== ERROR: AddressSanitizer heap-use-after-free on address 0x7f7ddab8c084 at pc 0x403c8c bp 0x7fff87fb82d0 sp 0x7fff87fb82c8 96e5dd7070Spatrick READ of size 4 at 0x7f7ddab8c084 thread T0 97e5dd7070Spatrick #0 0x403c8c in main example_UseAfterFree.cc:4 98e5dd7070Spatrick #1 0x7f7ddabcac4d in __libc_start_main ??:0 99e5dd7070Spatrick 0x7f7ddab8c084 is located 4 bytes inside of 400-byte region [0x7f7ddab8c080,0x7f7ddab8c210) 100e5dd7070Spatrick freed by thread T0 here: 101e5dd7070Spatrick #0 0x404704 in operator delete[](void*) ??:0 102e5dd7070Spatrick #1 0x403c53 in main example_UseAfterFree.cc:4 103e5dd7070Spatrick #2 0x7f7ddabcac4d in __libc_start_main ??:0 104e5dd7070Spatrick previously allocated by thread T0 here: 105e5dd7070Spatrick #0 0x404544 in operator new[](unsigned long) ??:0 106e5dd7070Spatrick #1 0x403c43 in main example_UseAfterFree.cc:2 107e5dd7070Spatrick #2 0x7f7ddabcac4d in __libc_start_main ??:0 108e5dd7070Spatrick ==9442== ABORTING 109e5dd7070Spatrick 110e5dd7070SpatrickIf that does not work for you (e.g. your process is sandboxed), you can use a 111e5dd7070Spatrickseparate script to symbolize the result offline (online symbolization can be 112e5dd7070Spatrickforce disabled by setting ``ASAN_OPTIONS=symbolize=0``): 113e5dd7070Spatrick 114e5dd7070Spatrick.. code-block:: console 115e5dd7070Spatrick 116e5dd7070Spatrick % ASAN_OPTIONS=symbolize=0 ./a.out 2> log 117e5dd7070Spatrick % projects/compiler-rt/lib/asan/scripts/asan_symbolize.py / < log | c++filt 118e5dd7070Spatrick ==9442== ERROR: AddressSanitizer heap-use-after-free on address 0x7f7ddab8c084 at pc 0x403c8c bp 0x7fff87fb82d0 sp 0x7fff87fb82c8 119e5dd7070Spatrick READ of size 4 at 0x7f7ddab8c084 thread T0 120e5dd7070Spatrick #0 0x403c8c in main example_UseAfterFree.cc:4 121e5dd7070Spatrick #1 0x7f7ddabcac4d in __libc_start_main ??:0 122e5dd7070Spatrick ... 123e5dd7070Spatrick 124e5dd7070SpatrickNote that on macOS you may need to run ``dsymutil`` on your binary to have the 125e5dd7070Spatrickfile\:line info in the AddressSanitizer reports. 126e5dd7070Spatrick 127e5dd7070SpatrickAdditional Checks 128e5dd7070Spatrick================= 129e5dd7070Spatrick 130e5dd7070SpatrickInitialization order checking 131e5dd7070Spatrick----------------------------- 132e5dd7070Spatrick 133e5dd7070SpatrickAddressSanitizer can optionally detect dynamic initialization order problems, 134e5dd7070Spatrickwhen initialization of globals defined in one translation unit uses 135e5dd7070Spatrickglobals defined in another translation unit. To enable this check at runtime, 136e5dd7070Spatrickyou should set environment variable 137e5dd7070Spatrick``ASAN_OPTIONS=check_initialization_order=1``. 138e5dd7070Spatrick 139e5dd7070SpatrickNote that this option is not supported on macOS. 140e5dd7070Spatrick 141a9ac8606SpatrickStack Use After Return (UAR) 142a9ac8606Spatrick---------------------------- 143a9ac8606Spatrick 144a9ac8606SpatrickAddressSanitizer can optionally detect stack use after return problems. 145a9ac8606SpatrickThis is available by default, or explicitly 146a9ac8606Spatrick(``-fsanitize-address-use-after-return=runtime``). 147*12c85518SrobertTo disable this check at runtime, set the environment variable 148*12c85518Srobert``ASAN_OPTIONS=detect_stack_use_after_return=0``. 149a9ac8606Spatrick 150a9ac8606SpatrickEnabling this check (``-fsanitize-address-use-after-return=always``) will 151a9ac8606Spatrickreduce code size. The code size may be reduced further by completely 152a9ac8606Spatrickeliminating this check (``-fsanitize-address-use-after-return=never``). 153a9ac8606Spatrick 154a9ac8606SpatrickTo summarize: ``-fsanitize-address-use-after-return=<mode>`` 155a9ac8606Spatrick * ``never``: Completely disables detection of UAR errors (reduces code size). 156*12c85518Srobert * ``runtime``: Adds the code for detection, but it can be disable via the 157*12c85518Srobert runtime environment (``ASAN_OPTIONS=detect_stack_use_after_return=0``). 158a9ac8606Spatrick * ``always``: Enables detection of UAR errors in all cases. (reduces code 159a9ac8606Spatrick size, but not as much as ``never``). 160a9ac8606Spatrick 161e5dd7070SpatrickMemory leak detection 162e5dd7070Spatrick--------------------- 163e5dd7070Spatrick 164e5dd7070SpatrickFor more information on leak detector in AddressSanitizer, see 165e5dd7070Spatrick:doc:`LeakSanitizer`. The leak detection is turned on by default on Linux, 166e5dd7070Spatrickand can be enabled using ``ASAN_OPTIONS=detect_leaks=1`` on macOS; 167e5dd7070Spatrickhowever, it is not yet supported on other platforms. 168e5dd7070Spatrick 169e5dd7070SpatrickIssue Suppression 170e5dd7070Spatrick================= 171e5dd7070Spatrick 172e5dd7070SpatrickAddressSanitizer is not expected to produce false positives. If you see one, 173e5dd7070Spatricklook again; most likely it is a true positive! 174e5dd7070Spatrick 175e5dd7070SpatrickSuppressing Reports in External Libraries 176e5dd7070Spatrick----------------------------------------- 177e5dd7070SpatrickRuntime interposition allows AddressSanitizer to find bugs in code that is 178e5dd7070Spatricknot being recompiled. If you run into an issue in external libraries, we 179e5dd7070Spatrickrecommend immediately reporting it to the library maintainer so that it 180e5dd7070Spatrickgets addressed. However, you can use the following suppression mechanism 181e5dd7070Spatrickto unblock yourself and continue on with the testing. This suppression 182e5dd7070Spatrickmechanism should only be used for suppressing issues in external code; it 183e5dd7070Spatrickdoes not work on code recompiled with AddressSanitizer. To suppress errors 184e5dd7070Spatrickin external libraries, set the ``ASAN_OPTIONS`` environment variable to point 185e5dd7070Spatrickto a suppression file. You can either specify the full path to the file or the 186e5dd7070Spatrickpath of the file relative to the location of your executable. 187e5dd7070Spatrick 188e5dd7070Spatrick.. code-block:: bash 189e5dd7070Spatrick 190e5dd7070Spatrick ASAN_OPTIONS=suppressions=MyASan.supp 191e5dd7070Spatrick 192e5dd7070SpatrickUse the following format to specify the names of the functions or libraries 193e5dd7070Spatrickyou want to suppress. You can see these in the error report. Remember that 194e5dd7070Spatrickthe narrower the scope of the suppression, the more bugs you will be able to 195e5dd7070Spatrickcatch. 196e5dd7070Spatrick 197e5dd7070Spatrick.. code-block:: bash 198e5dd7070Spatrick 199e5dd7070Spatrick interceptor_via_fun:NameOfCFunctionToSuppress 200e5dd7070Spatrick interceptor_via_fun:-[ClassName objCMethodToSuppress:] 201e5dd7070Spatrick interceptor_via_lib:NameOfTheLibraryToSuppress 202e5dd7070Spatrick 203e5dd7070SpatrickConditional Compilation with ``__has_feature(address_sanitizer)`` 204e5dd7070Spatrick----------------------------------------------------------------- 205e5dd7070Spatrick 206e5dd7070SpatrickIn some cases one may need to execute different code depending on whether 207e5dd7070SpatrickAddressSanitizer is enabled. 208e5dd7070Spatrick:ref:`\_\_has\_feature <langext-__has_feature-__has_extension>` can be used for 209e5dd7070Spatrickthis purpose. 210e5dd7070Spatrick 211e5dd7070Spatrick.. code-block:: c 212e5dd7070Spatrick 213e5dd7070Spatrick #if defined(__has_feature) 214e5dd7070Spatrick # if __has_feature(address_sanitizer) 215e5dd7070Spatrick // code that builds only under AddressSanitizer 216e5dd7070Spatrick # endif 217e5dd7070Spatrick #endif 218e5dd7070Spatrick 219e5dd7070SpatrickDisabling Instrumentation with ``__attribute__((no_sanitize("address")))`` 220e5dd7070Spatrick-------------------------------------------------------------------------- 221e5dd7070Spatrick 222e5dd7070SpatrickSome code should not be instrumented by AddressSanitizer. One may use 223e5dd7070Spatrickthe attribute ``__attribute__((no_sanitize("address")))`` (which has 224e5dd7070Spatrickdeprecated synonyms `no_sanitize_address` and 225e5dd7070Spatrick`no_address_safety_analysis`) to disable instrumentation of a 226e5dd7070Spatrickparticular function. This attribute may not be supported by other 227e5dd7070Spatrickcompilers, so we suggest to use it together with 228e5dd7070Spatrick``__has_feature(address_sanitizer)``. 229e5dd7070Spatrick 230e5dd7070SpatrickThe same attribute used on a global variable prevents AddressSanitizer 231e5dd7070Spatrickfrom adding redzones around it and detecting out of bounds accesses. 232e5dd7070Spatrick 233*12c85518Srobert 234*12c85518SrobertAddressSanitizer also supports 235*12c85518Srobert``__attribute__((disable_sanitizer_instrumentation))``. This attribute 236*12c85518Srobertworks similar to ``__attribute__((no_sanitize("address")))``, but it also 237*12c85518Srobertprevents instrumentation performed by other sanitizers. 238*12c85518Srobert 239a9ac8606SpatrickSuppressing Errors in Recompiled Code (Ignorelist) 240a9ac8606Spatrick-------------------------------------------------- 241e5dd7070Spatrick 242e5dd7070SpatrickAddressSanitizer supports ``src`` and ``fun`` entity types in 243e5dd7070Spatrick:doc:`SanitizerSpecialCaseList`, that can be used to suppress error reports 244e5dd7070Spatrickin the specified source files or functions. Additionally, AddressSanitizer 245e5dd7070Spatrickintroduces ``global`` and ``type`` entity types that can be used to 246e5dd7070Spatricksuppress error reports for out-of-bound access to globals with certain 247e5dd7070Spatricknames and types (you may only specify class or struct types). 248e5dd7070Spatrick 249e5dd7070SpatrickYou may use an ``init`` category to suppress reports about initialization-order 250e5dd7070Spatrickproblems happening in certain source files or with certain global variables. 251e5dd7070Spatrick 252e5dd7070Spatrick.. code-block:: bash 253e5dd7070Spatrick 254e5dd7070Spatrick # Suppress error reports for code in a file or in a function: 255e5dd7070Spatrick src:bad_file.cpp 256e5dd7070Spatrick # Ignore all functions with names containing MyFooBar: 257e5dd7070Spatrick fun:*MyFooBar* 258e5dd7070Spatrick # Disable out-of-bound checks for global: 259e5dd7070Spatrick global:bad_array 260e5dd7070Spatrick # Disable out-of-bound checks for global instances of a given class ... 261e5dd7070Spatrick type:Namespace::BadClassName 262e5dd7070Spatrick # ... or a given struct. Use wildcard to deal with anonymous namespace. 263e5dd7070Spatrick type:Namespace2::*::BadStructName 264e5dd7070Spatrick # Disable initialization-order checks for globals: 265e5dd7070Spatrick global:bad_init_global=init 266e5dd7070Spatrick type:*BadInitClassSubstring*=init 267e5dd7070Spatrick src:bad/init/files/*=init 268e5dd7070Spatrick 269e5dd7070SpatrickSuppressing memory leaks 270e5dd7070Spatrick------------------------ 271e5dd7070Spatrick 272e5dd7070SpatrickMemory leak reports produced by :doc:`LeakSanitizer` (if it is run as a part 273e5dd7070Spatrickof AddressSanitizer) can be suppressed by a separate file passed as 274e5dd7070Spatrick 275e5dd7070Spatrick.. code-block:: bash 276e5dd7070Spatrick 277e5dd7070Spatrick LSAN_OPTIONS=suppressions=MyLSan.supp 278e5dd7070Spatrick 279e5dd7070Spatrickwhich contains lines of the form `leak:<pattern>`. Memory leak will be 280e5dd7070Spatricksuppressed if pattern matches any function name, source file name, or 281e5dd7070Spatricklibrary name in the symbolized stack trace of the leak report. See 282e5dd7070Spatrick`full documentation 283e5dd7070Spatrick<https://github.com/google/sanitizers/wiki/AddressSanitizerLeakSanitizer#suppressions>`_ 284e5dd7070Spatrickfor more details. 285e5dd7070Spatrick 286a9ac8606SpatrickCode generation control 287a9ac8606Spatrick======================= 288a9ac8606Spatrick 289a9ac8606SpatrickInstrumentation code outlining 290a9ac8606Spatrick------------------------------ 291a9ac8606Spatrick 292*12c85518SrobertBy default AddressSanitizer inlines the instrumentation code to improve the 293a9ac8606Spatrickrun-time performance, which leads to increased binary size. Using the 294a9ac8606Spatrick(clang flag ``-fsanitize-address-outline-instrumentation` default: ``false``) 295*12c85518Srobertflag forces all code instrumentation to be outlined, which reduces the size 296*12c85518Srobertof the generated code, but also reduces the run-time performance. 297a9ac8606Spatrick 298e5dd7070SpatrickLimitations 299e5dd7070Spatrick=========== 300e5dd7070Spatrick 301e5dd7070Spatrick* AddressSanitizer uses more real memory than a native run. Exact overhead 302e5dd7070Spatrick depends on the allocations sizes. The smaller the allocations you make the 303e5dd7070Spatrick bigger the overhead is. 304e5dd7070Spatrick* AddressSanitizer uses more stack memory. We have seen up to 3x increase. 305e5dd7070Spatrick* On 64-bit platforms AddressSanitizer maps (but not reserves) 16+ Terabytes of 306e5dd7070Spatrick virtual address space. This means that tools like ``ulimit`` may not work as 307e5dd7070Spatrick usually expected. 308e5dd7070Spatrick* Static linking of executables is not supported. 309e5dd7070Spatrick 310e5dd7070SpatrickSupported Platforms 311e5dd7070Spatrick=================== 312e5dd7070Spatrick 313e5dd7070SpatrickAddressSanitizer is supported on: 314e5dd7070Spatrick 315e5dd7070Spatrick* Linux i386/x86\_64 (tested on Ubuntu 12.04) 316e5dd7070Spatrick* macOS 10.7 - 10.11 (i386/x86\_64) 317e5dd7070Spatrick* iOS Simulator 318e5dd7070Spatrick* Android ARM 319e5dd7070Spatrick* NetBSD i386/x86\_64 320e5dd7070Spatrick* FreeBSD i386/x86\_64 (tested on FreeBSD 11-current) 321e5dd7070Spatrick* Windows 8.1+ (i386/x86\_64) 322e5dd7070Spatrick 323e5dd7070SpatrickPorts to various other platforms are in progress. 324e5dd7070Spatrick 325e5dd7070SpatrickCurrent Status 326e5dd7070Spatrick============== 327e5dd7070Spatrick 328e5dd7070SpatrickAddressSanitizer is fully functional on supported platforms starting from LLVM 329e5dd7070Spatrick3.1. The test suite is integrated into CMake build and can be run with ``make 330e5dd7070Spatrickcheck-asan`` command. 331e5dd7070Spatrick 332e5dd7070SpatrickThe Windows port is functional and is used by Chrome and Firefox, but it is not 333e5dd7070Spatrickas well supported as the other ports. 334e5dd7070Spatrick 335e5dd7070SpatrickMore Information 336e5dd7070Spatrick================ 337e5dd7070Spatrick 338e5dd7070Spatrick`<https://github.com/google/sanitizers/wiki/AddressSanitizer>`_ 339