head 1.1; branch 1.1.1; access; symbols netbsd-10-2-RELEASE:1.1.1.8 netbsd-9-5-RELEASE:1.1.1.7 netbsd-11-0-RELEASE:1.1.1.8 netbsd-11-0-RC7:1.1.1.8 netbsd-11-0-RC6:1.1.1.8 netbsd-11-0-RC5:1.1.1.8 netbsd-11-0-RC4:1.1.1.8 netbsd-11-0-RC3:1.1.1.8 netbsd-11-0-RC2:1.1.1.8 netbsd-11-0-RC1:1.1.1.8 perseant-exfatfs-base-20250801:1.1.1.8 netbsd-11:1.1.1.8.0.10 netbsd-11-base:1.1.1.8 netbsd-10-1-RELEASE:1.1.1.8 perseant-exfatfs-base-20240630:1.1.1.8 perseant-exfatfs:1.1.1.8.0.8 perseant-exfatfs-base:1.1.1.8 netbsd-8-3-RELEASE:1.1.1.6 netbsd-9-4-RELEASE:1.1.1.7 netbsd-10-0-RELEASE:1.1.1.8 netbsd-10-0-RC6:1.1.1.8 netbsd-10-0-RC5:1.1.1.8 netbsd-10-0-RC4:1.1.1.8 netbsd-10-0-RC3:1.1.1.8 netbsd-10-0-RC2:1.1.1.8 netbsd-10-0-RC1:1.1.1.8 netbsd-10:1.1.1.8.0.6 netbsd-10-base:1.1.1.8 netbsd-9-3-RELEASE:1.1.1.7 cjep_sun2x:1.1.1.8.0.4 cjep_sun2x-base:1.1.1.8 cjep_staticlib_x-base1:1.1.1.8 netbsd-9-2-RELEASE:1.1.1.7 cjep_staticlib_x:1.1.1.8.0.2 cjep_staticlib_x-base:1.1.1.8 netbsd-9-1-RELEASE:1.1.1.7 phil-wifi-20200421:1.1.1.8 phil-wifi-20200411:1.1.1.8 phil-wifi-20200406:1.1.1.8 netbsd-8-2-RELEASE:1.1.1.6 netbsd-9-0-RELEASE:1.1.1.7 netbsd-9-0-RC2:1.1.1.7 netbsd-9-0-RC1:1.1.1.7 netbsd-9:1.1.1.7.0.2 netbsd-9-base:1.1.1.7 phil-wifi-20190609:1.1.1.7 netbsd-8-1-RELEASE:1.1.1.6 netbsd-8-1-RC1:1.1.1.6 pgoyette-compat-merge-20190127:1.1.1.6.12.1 pgoyette-compat-20190127:1.1.1.7 pgoyette-compat-20190118:1.1.1.7 pgoyette-compat-1226:1.1.1.7 pgoyette-compat-1126:1.1.1.7 pgoyette-compat-1020:1.1.1.7 pgoyette-compat-0930:1.1.1.7 pgoyette-compat-0906:1.1.1.7 netbsd-7-2-RELEASE:1.1.1.3.6.1 pgoyette-compat-0728:1.1.1.7 clang-337282:1.1.1.7 netbsd-8-0-RELEASE:1.1.1.6 phil-wifi:1.1.1.6.0.14 phil-wifi-base:1.1.1.6 pgoyette-compat-0625:1.1.1.6 netbsd-8-0-RC2:1.1.1.6 pgoyette-compat-0521:1.1.1.6 pgoyette-compat-0502:1.1.1.6 pgoyette-compat-0422:1.1.1.6 netbsd-8-0-RC1:1.1.1.6 pgoyette-compat-0415:1.1.1.6 pgoyette-compat-0407:1.1.1.6 pgoyette-compat-0330:1.1.1.6 pgoyette-compat-0322:1.1.1.6 pgoyette-compat-0315:1.1.1.6 netbsd-7-1-2-RELEASE:1.1.1.3.6.1 pgoyette-compat:1.1.1.6.0.12 pgoyette-compat-base:1.1.1.6 netbsd-7-1-1-RELEASE:1.1.1.3.6.1 clang-319952:1.1.1.6 matt-nb8-mediatek:1.1.1.6.0.10 matt-nb8-mediatek-base:1.1.1.6 clang-309604:1.1.1.6 perseant-stdc-iso10646:1.1.1.6.0.8 perseant-stdc-iso10646-base:1.1.1.6 netbsd-8:1.1.1.6.0.6 netbsd-8-base:1.1.1.6 prg-localcount2-base3:1.1.1.6 prg-localcount2-base2:1.1.1.6 prg-localcount2-base1:1.1.1.6 prg-localcount2:1.1.1.6.0.4 prg-localcount2-base:1.1.1.6 pgoyette-localcount-20170426:1.1.1.6 bouyer-socketcan-base1:1.1.1.6 pgoyette-localcount-20170320:1.1.1.6 netbsd-7-1:1.1.1.3.6.1.0.6 netbsd-7-1-RELEASE:1.1.1.3.6.1 netbsd-7-1-RC2:1.1.1.3.6.1 clang-294123:1.1.1.6 netbsd-7-nhusb-base-20170116:1.1.1.3.6.1 bouyer-socketcan:1.1.1.6.0.2 bouyer-socketcan-base:1.1.1.6 clang-291444:1.1.1.6 pgoyette-localcount-20170107:1.1.1.5 netbsd-7-1-RC1:1.1.1.3.6.1 pgoyette-localcount-20161104:1.1.1.5 netbsd-7-0-2-RELEASE:1.1.1.3.6.1 localcount-20160914:1.1.1.5 netbsd-7-nhusb:1.1.1.3.6.1.0.4 netbsd-7-nhusb-base:1.1.1.3.6.1 clang-280599:1.1.1.5 pgoyette-localcount-20160806:1.1.1.5 pgoyette-localcount-20160726:1.1.1.5 pgoyette-localcount:1.1.1.5.0.2 pgoyette-localcount-base:1.1.1.5 netbsd-7-0-1-RELEASE:1.1.1.3.6.1 clang-261930:1.1.1.5 netbsd-7-0:1.1.1.3.6.1.0.2 netbsd-7-0-RELEASE:1.1.1.3.6.1 netbsd-7-0-RC3:1.1.1.3.6.1 netbsd-7-0-RC2:1.1.1.3.6.1 netbsd-7-0-RC1:1.1.1.3.6.1 clang-237755:1.1.1.4 clang-232565:1.1.1.4 clang-227398:1.1.1.4 tls-maxphys-base:1.1.1.3 tls-maxphys:1.1.1.3.0.8 netbsd-7:1.1.1.3.0.6 netbsd-7-base:1.1.1.3 clang-215315:1.1.1.3 clang-209886:1.1.1.3 yamt-pagecache:1.1.1.3.0.4 yamt-pagecache-base9:1.1.1.3 tls-earlyentropy:1.1.1.3.0.2 tls-earlyentropy-base:1.1.1.3 riastradh-xf86-video-intel-2-7-1-pre-2-21-15:1.1.1.3 riastradh-drm2-base3:1.1.1.3 clang-202566:1.1.1.3 clang-201163:1.1.1.3 clang-199312:1.1.1.2 clang-198450:1.1.1.2 clang-196603:1.1.1.1 clang-195771:1.1.1.1 LLVM:1.1.1; locks; strict; comment @# @; 1.1 date 2013.11.28.14.14.47; author joerg; state Exp; branches 1.1.1.1; next ; commitid ow8OybrawrB1f3fx; 1.1.1.1 date 2013.11.28.14.14.47; author joerg; state Exp; branches; next 1.1.1.2; commitid ow8OybrawrB1f3fx; 1.1.1.2 date 2014.01.05.15.37.44; author joerg; state Exp; branches; next 1.1.1.3; commitid wh3aCSIWykURqWjx; 1.1.1.3 date 2014.02.14.20.07.00; author joerg; state Exp; branches 1.1.1.3.4.1 1.1.1.3.6.1 1.1.1.3.8.1; next 1.1.1.4; commitid annVkZ1sc17rF6px; 1.1.1.4 date 2015.01.29.19.57.42; author joerg; state Exp; branches; next 1.1.1.5; commitid mlISSizlPKvepX7y; 1.1.1.5 date 2016.02.27.22.10.56; author joerg; state Exp; branches 1.1.1.5.2.1; next 1.1.1.6; commitid tIimz3oDlh1NpBWy; 1.1.1.6 date 2017.01.11.10.40.26; author joerg; state Exp; branches 1.1.1.6.12.1 1.1.1.6.14.1; next 1.1.1.7; commitid CNnUNfII1jgNmxBz; 1.1.1.7 date 2018.07.17.18.32.11; author joerg; state Exp; branches; next 1.1.1.8; commitid wDzL46ALjrCZgwKA; 1.1.1.8 date 2019.11.13.22.19.10; author joerg; state dead; branches; next ; commitid QD8YATxuNG34YJKB; 1.1.1.3.4.1 date 2014.02.14.20.07.00; author yamt; state dead; branches; next 1.1.1.3.4.2; commitid WSrDtL5nYAUyiyBx; 1.1.1.3.4.2 date 2014.05.22.16.18.18; author yamt; state Exp; branches; next ; commitid WSrDtL5nYAUyiyBx; 1.1.1.3.6.1 date 2015.06.04.20.04.23; author snj; state Exp; branches; next ; commitid yRnjq9fueSo6n9oy; 1.1.1.3.8.1 date 2014.02.14.20.07.00; author tls; state dead; branches; next 1.1.1.3.8.2; commitid jTnpym9Qu0o4R1Nx; 1.1.1.3.8.2 date 2014.08.19.23.47.19; author tls; state Exp; branches; next ; commitid jTnpym9Qu0o4R1Nx; 1.1.1.5.2.1 date 2017.03.20.06.52.30; author pgoyette; state Exp; branches; next ; commitid jjw7cAwgyKq7RfKz; 1.1.1.6.12.1 date 2018.07.28.04.33.07; author pgoyette; state Exp; branches; next ; commitid 1UP1xAIUxv1ZgRLA; 1.1.1.6.14.1 date 2019.06.10.21.45.08; author christos; state Exp; branches; next 1.1.1.6.14.2; commitid jtc8rnCzWiEEHGqB; 1.1.1.6.14.2 date 2020.04.13.07.46.20; author martin; state dead; branches; next ; commitid X01YhRUPVUDaec4C; desc @@ 1.1 log @Initial revision @ text @================ AddressSanitizer ================ .. contents:: :local: Introduction ============ AddressSanitizer is a fast memory error detector. It consists of a compiler instrumentation module and a run-time library. The tool can detect the following types of bugs: * Out-of-bounds accesses to heap, stack and globals * Use-after-free * Use-after-return (to some extent) * Double-free, invalid free Typical slowdown introduced by AddressSanitizer is **2x**. How to build ============ Follow the `clang build instructions <../get_started.html>`_. CMake build is supported. Usage ===== Simply compile and link your program with ``-fsanitize=address`` flag. The AddressSanitizer run-time library should be linked to the final executable, so make sure to use ``clang`` (not ``ld``) for the final link step. When linking shared libraries, the AddressSanitizer run-time is not linked, so ``-Wl,-z,defs`` may cause link errors (don't use it with AddressSanitizer). To get a reasonable performance add ``-O1`` or higher. To get nicer stack traces in error messages add ``-fno-omit-frame-pointer``. To get perfect stack traces you may need to disable inlining (just use ``-O1``) and tail call elimination (``-fno-optimize-sibling-calls``). .. code-block:: console % cat example_UseAfterFree.cc int main(int argc, char **argv) { int *array = new int[100]; delete [] array; return array[argc]; // BOOM } # Compile and link % clang -O1 -g -fsanitize=address -fno-omit-frame-pointer example_UseAfterFree.cc or: .. code-block:: console # Compile % clang -O1 -g -fsanitize=address -fno-omit-frame-pointer -c example_UseAfterFree.cc # Link % clang -g -fsanitize=address example_UseAfterFree.o If a bug is detected, the program will print an error message to stderr and exit with a non-zero exit code. Currently, AddressSanitizer does not symbolize its output, so you may need to use a separate script to symbolize the result offline (this will be fixed in future). .. code-block:: console % ./a.out 2> log % projects/compiler-rt/lib/asan/scripts/asan_symbolize.py / < log | c++filt ==9442== ERROR: AddressSanitizer heap-use-after-free on address 0x7f7ddab8c084 at pc 0x403c8c bp 0x7fff87fb82d0 sp 0x7fff87fb82c8 READ of size 4 at 0x7f7ddab8c084 thread T0 #0 0x403c8c in main example_UseAfterFree.cc:4 #1 0x7f7ddabcac4d in __libc_start_main ??:0 0x7f7ddab8c084 is located 4 bytes inside of 400-byte region [0x7f7ddab8c080,0x7f7ddab8c210) freed by thread T0 here: #0 0x404704 in operator delete[](void*) ??:0 #1 0x403c53 in main example_UseAfterFree.cc:4 #2 0x7f7ddabcac4d in __libc_start_main ??:0 previously allocated by thread T0 here: #0 0x404544 in operator new[](unsigned long) ??:0 #1 0x403c43 in main example_UseAfterFree.cc:2 #2 0x7f7ddabcac4d in __libc_start_main ??:0 ==9442== ABORTING AddressSanitizer exits on the first detected error. This is by design. One reason: it makes the generated code smaller and faster (both by ~5%). Another reason: this makes fixing bugs unavoidable. With Valgrind, it is often the case that users treat Valgrind warnings as false positives (which they are not) and don't fix them. ``__has_feature(address_sanitizer)`` ------------------------------------ In some cases one may need to execute different code depending on whether AddressSanitizer is enabled. :ref:`\_\_has\_feature ` can be used for this purpose. .. code-block:: c #if defined(__has_feature) # if __has_feature(address_sanitizer) // code that builds only under AddressSanitizer # endif #endif ``__attribute__((no_sanitize_address))`` ----------------------------------------------- Some code should not be instrumented by AddressSanitizer. One may use the function attribute :ref:`no_sanitize_address ` (or a deprecated synonym `no_address_safety_analysis`) to disable instrumentation of a particular function. This attribute may not be supported by other compilers, so we suggest to use it together with ``__has_feature(address_sanitizer)``. Initialization order checking ----------------------------- AddressSanitizer can optionally detect dynamic initialization order problems, when initialization of globals defined in one translation unit uses globals defined in another translation unit. To enable this check at runtime, you should set environment variable ``ASAN_OPTIONS=check_initialization_order=1``. Blacklist --------- AddressSanitizer supports ``src`` and ``fun`` entity types in :doc:`SanitizerSpecialCaseList`, that can be used to suppress error reports in the specified source files or functions. Additionally, AddressSanitizer introduces ``global`` and ``type`` entity types that can be used to suppress error reports for out-of-bound access to globals with certain names and types (you may only specify class or struct types). You may use an ``init`` category to suppress reports about initialization-order problems happening in certain source files or with certain global variables. .. code-block:: bash # Suppress error reports for code in a file or in a function: src:bad_file.cpp # Ignore all functions with names containing MyFooBar: fun:*MyFooBar* # Disable out-of-bound checks for global: global:bad_array # Disable out-of-bound checks for global instances of a given class ... type:class.Namespace::BadClassName # ... or a given struct. Use wildcard to deal with anonymous namespace. type:struct.Namespace2::*::BadStructName # Disable initialization-order checks for globals: global:bad_init_global=init type:*BadInitClassSubstring*=init src:bad/init/files/*=init Supported Platforms =================== AddressSanitizer is supported on * Linux i386/x86\_64 (tested on Ubuntu 10.04 and 12.04); * MacOS 10.6, 10.7 and 10.8 (i386/x86\_64). Support for Linux ARM (and Android ARM) is in progress (it may work, but is not guaranteed too). Limitations =========== * AddressSanitizer uses more real memory than a native run. Exact overhead depends on the allocations sizes. The smaller the allocations you make the bigger the overhead is. * AddressSanitizer uses more stack memory. We have seen up to 3x increase. * On 64-bit platforms AddressSanitizer maps (but not reserves) 16+ Terabytes of virtual address space. This means that tools like ``ulimit`` may not work as usually expected. * Static linking is not supported. Current Status ============== AddressSanitizer is fully functional on supported platforms starting from LLVM 3.1. The test suite is integrated into CMake build and can be run with ``make check-asan`` command. More Information ================ `http://code.google.com/p/address-sanitizer `_ @ 1.1.1.1 log @Import Clang 3.4rc1 r195771. @ text @@ 1.1.1.2 log @Import clang 3.5svn r198450. @ text @a18 1 * Memory leaks (experimental) a157 6 Memory leak detection --------------------- For the experimental memory leak detector in AddressSanitizer, see :doc:`LeakSanitizer`. @ 1.1.1.3 log @Import Clang 3.5svn r201163. @ text @d64 3 a66 4 exit with a non-zero exit code. To make AddressSanitizer symbolize its output you need to set the ``ASAN_SYMBOLIZER_PATH`` environment variable to point to the ``llvm-symbolizer`` binary (or make sure ``llvm-symbolizer`` is in your ``$PATH``): d70 2 a71 1 % ASAN_SYMBOLIZER_PATH=/usr/local/bin/llvm-symbolizer ./a.out a86 17 If that does not work for you (e.g. your process is sandboxed), you can use a separate script to symbolize the result offline (online symbolization can be force disabled by setting ``ASAN_OPTIONS=symbolize=0``): .. code-block:: console % ASAN_OPTIONS=symbolize=0 ./a.out 2> log % projects/compiler-rt/lib/asan/scripts/asan_symbolize.py / < log | c++filt ==9442== ERROR: AddressSanitizer heap-use-after-free on address 0x7f7ddab8c084 at pc 0x403c8c bp 0x7fff87fb82d0 sp 0x7fff87fb82c8 READ of size 4 at 0x7f7ddab8c084 thread T0 #0 0x403c8c in main example_UseAfterFree.cc:4 #1 0x7f7ddabcac4d in __libc_start_main ??:0 ... Note that on OS X you may need to run ``dsymutil`` on your binary to have the file\:line info in the AddressSanitizer reports. d170 2 a171 3 * Linux i386/x86\_64 (tested on Ubuntu 12.04); * MacOS 10.6 - 10.9 (i386/x86\_64). * Android ARM d173 2 a174 1 Ports to various other platforms are in progress. @ 1.1.1.3.6.1 log @Update LLVM to 3.6.1, requested by joerg in ticket 824. @ text @d168 1 a168 1 type:Namespace::BadClassName d170 1 a170 1 type:Namespace2::*::BadStructName a189 1 * FreeBSD i386/x86\_64 (tested on FreeBSD 11-current) @ 1.1.1.4 log @Import Clang 3.6RC1 r227398. @ text @d168 1 a168 1 type:Namespace::BadClassName d170 1 a170 1 type:Namespace2::*::BadStructName a189 1 * FreeBSD i386/x86\_64 (tested on FreeBSD 11-current) @ 1.1.1.5 log @Import Clang 3.8.0rc3 r261930. @ text @d26 2 a27 1 Build LLVM/Clang with `CMake `_. d64 1 a64 22 exit with a non-zero exit code. AddressSanitizer exits on the first detected error. This is by design: * This approach allows AddressSanitizer to produce faster and smaller generated code (both by ~5%). * Fixing bugs becomes unavoidable. AddressSanitizer does not produce false alarms. Once a memory corruption occurs, the program is in an inconsistent state, which could lead to confusing results and potentially misleading subsequent reports. If your process is sandboxed and you are running on OS X 10.10 or earlier, you will need to set ``DYLD_INSERT_LIBRARIES`` environment variable and point it to the ASan library that is packaged with the compiler used to build the executable. (You can find the library by searching for dynamic libraries with ``asan`` in their name.) If the environment variable is not set, the process will try to re-exec. Also keep in mind that when moving the executable to another machine, the ASan library will also need to be copied over. Symbolizing the Reports ========================= To make AddressSanitizer symbolize its output d104 5 a108 48 Additional Checks ================= Initialization order checking ----------------------------- AddressSanitizer can optionally detect dynamic initialization order problems, when initialization of globals defined in one translation unit uses globals defined in another translation unit. To enable this check at runtime, you should set environment variable ``ASAN_OPTIONS=check_initialization_order=1``. Note that this option is not supported on OS X. Memory leak detection --------------------- For more information on leak detector in AddressSanitizer, see :doc:`LeakSanitizer`. The leak detection is turned on by default on Linux; however, it is not yet supported on other platforms. Issue Suppression ================= AddressSanitizer is not expected to produce false positives. If you see one, look again; most likely it is a true positive! Suppressing Reports in External Libraries ----------------------------------------- Runtime interposition allows AddressSanitizer to find bugs in code that is not being recompiled. If you run into an issue in external libraries, we recommend immediately reporting it to the library maintainer so that it gets addressed. However, you can use the following suppression mechanism to unblock yourself and continue on with the testing. This suppression mechanism should only be used for suppressing issues in external code; it does not work on code recompiled with AddressSanitizer. To suppress errors in external libraries, set the ``ASAN_OPTIONS`` environment variable to point to a suppression file. You can either specify the full path to the file or the path of the file relative to the location of your executable. .. code-block:: bash ASAN_OPTIONS=suppressions=MyASan.supp Use the following format to specify the names of the functions or libraries you want to suppress. You can see these in the error report. Remember that the narrower the scope of the suppression, the more bugs you will be able to catch. d110 2 a111 8 .. code-block:: bash interceptor_via_fun:NameOfCFunctionToSuppress interceptor_via_fun:-[ClassName objCMethodToSuppress:] interceptor_via_lib:NameOfTheLibraryToSuppress Conditional Compilation with ``__has_feature(address_sanitizer)`` ----------------------------------------------------------------- d126 2 a127 2 Disabling Instrumentation with ``__attribute__((no_sanitize("address")))`` -------------------------------------------------------------------------- d130 4 a133 3 function attribute ``__attribute__((no_sanitize("address")))`` (which has deprecated synonyms `no_sanitize_address` and `no_address_safety_analysis`) to disable instrumentation of a particular function. This attribute may not be d137 11 a147 2 Suppressing Errors in Recompiled Code (Blacklist) ------------------------------------------------- d176 18 a205 13 Supported Platforms =================== AddressSanitizer is supported on: * Linux i386/x86\_64 (tested on Ubuntu 12.04) * OS X 10.7 - 10.11 (i386/x86\_64) * iOS Simulator * Android ARM * FreeBSD i386/x86\_64 (tested on FreeBSD 11-current) Ports to various other platforms are in progress. d216 2 a217 1 ``_ @ 1.1.1.5.2.1 log @Sync with HEAD @ text @d17 1 a17 2 * Use-after-return (runtime flag `ASAN_OPTIONS=detect_stack_use_after_return=1`) * Use-after-scope (clang flag `-fsanitize-address-use-after-scope`) d51 1 a51 1 % clang++ -O1 -g -fsanitize=address -fno-omit-frame-pointer example_UseAfterFree.cc d58 1 a58 1 % clang++ -O1 -g -fsanitize=address -fno-omit-frame-pointer -c example_UseAfterFree.cc d60 1 a60 1 % clang++ -g -fsanitize=address example_UseAfterFree.o a234 17 Suppressing memory leaks ------------------------ Memory leak reports produced by :doc:`LeakSanitizer` (if it is run as a part of AddressSanitizer) can be suppressed by a separate file passed as .. code-block:: bash LSAN_OPTIONS=suppressions=MyLSan.supp which contains lines of the form `leak:`. Memory leak will be suppressed if pattern matches any function name, source file name, or library name in the symbolized stack trace of the leak report. See `full documentation `_ for more details. @ 1.1.1.6 log @Import Clang pre-4.0.0 r291444. @ text @d17 1 a17 2 * Use-after-return (runtime flag `ASAN_OPTIONS=detect_stack_use_after_return=1`) * Use-after-scope (clang flag `-fsanitize-address-use-after-scope`) d51 1 a51 1 % clang++ -O1 -g -fsanitize=address -fno-omit-frame-pointer example_UseAfterFree.cc d58 1 a58 1 % clang++ -O1 -g -fsanitize=address -fno-omit-frame-pointer -c example_UseAfterFree.cc d60 1 a60 1 % clang++ -g -fsanitize=address example_UseAfterFree.o a234 17 Suppressing memory leaks ------------------------ Memory leak reports produced by :doc:`LeakSanitizer` (if it is run as a part of AddressSanitizer) can be suppressed by a separate file passed as .. code-block:: bash LSAN_OPTIONS=suppressions=MyLSan.supp which contains lines of the form `leak:`. Memory leak will be suppressed if pattern matches any function name, source file name, or library name in the symbolized stack trace of the leak report. See `full documentation `_ for more details. @ 1.1.1.6.14.1 log @Sync with HEAD @ text @d143 1 a143 2 :doc:`LeakSanitizer`. The leak detection is turned on by default on Linux, and can be enabled using ``ASAN_OPTIONS=detect_leaks=1`` on OS X; d199 5 a203 6 Some code should not be instrumented by AddressSanitizer. One may use the attribute ``__attribute__((no_sanitize("address")))`` (which has deprecated synonyms `no_sanitize_address` and `no_address_safety_analysis`) to disable instrumentation of a particular function. This attribute may not be supported by other compilers, so we suggest to use it together with a205 3 The same attribute used on a global variable prevents AddressSanitizer from adding redzones around it and detecting out of bounds accesses. @ 1.1.1.6.14.2 log @Mostly merge changes from HEAD upto 20200411 @ text @@ 1.1.1.6.12.1 log @Sync with HEAD @ text @d143 1 a143 2 :doc:`LeakSanitizer`. The leak detection is turned on by default on Linux, and can be enabled using ``ASAN_OPTIONS=detect_leaks=1`` on OS X; d199 5 a203 6 Some code should not be instrumented by AddressSanitizer. One may use the attribute ``__attribute__((no_sanitize("address")))`` (which has deprecated synonyms `no_sanitize_address` and `no_address_safety_analysis`) to disable instrumentation of a particular function. This attribute may not be supported by other compilers, so we suggest to use it together with a205 3 The same attribute used on a global variable prevents AddressSanitizer from adding redzones around it and detecting out of bounds accesses. @ 1.1.1.7 log @Import clang r337282 from trunk @ text @d143 1 a143 2 :doc:`LeakSanitizer`. The leak detection is turned on by default on Linux, and can be enabled using ``ASAN_OPTIONS=detect_leaks=1`` on OS X; d199 5 a203 6 Some code should not be instrumented by AddressSanitizer. One may use the attribute ``__attribute__((no_sanitize("address")))`` (which has deprecated synonyms `no_sanitize_address` and `no_address_safety_analysis`) to disable instrumentation of a particular function. This attribute may not be supported by other compilers, so we suggest to use it together with a205 3 The same attribute used on a global variable prevents AddressSanitizer from adding redzones around it and detecting out of bounds accesses. @ 1.1.1.8 log @Mark old LLVM instance as dead. @ text @@ 1.1.1.3.8.1 log @file AddressSanitizer.rst was added on branch tls-maxphys on 2014-08-19 23:47:19 +0000 @ text @d1 216 @ 1.1.1.3.8.2 log @Rebase to HEAD as of a few days ago. @ text @a0 216 ================ AddressSanitizer ================ .. contents:: :local: Introduction ============ AddressSanitizer is a fast memory error detector. It consists of a compiler instrumentation module and a run-time library. The tool can detect the following types of bugs: * Out-of-bounds accesses to heap, stack and globals * Use-after-free * Use-after-return (to some extent) * Double-free, invalid free * Memory leaks (experimental) Typical slowdown introduced by AddressSanitizer is **2x**. How to build ============ Follow the `clang build instructions <../get_started.html>`_. CMake build is supported. Usage ===== Simply compile and link your program with ``-fsanitize=address`` flag. The AddressSanitizer run-time library should be linked to the final executable, so make sure to use ``clang`` (not ``ld``) for the final link step. When linking shared libraries, the AddressSanitizer run-time is not linked, so ``-Wl,-z,defs`` may cause link errors (don't use it with AddressSanitizer). To get a reasonable performance add ``-O1`` or higher. To get nicer stack traces in error messages add ``-fno-omit-frame-pointer``. To get perfect stack traces you may need to disable inlining (just use ``-O1``) and tail call elimination (``-fno-optimize-sibling-calls``). .. code-block:: console % cat example_UseAfterFree.cc int main(int argc, char **argv) { int *array = new int[100]; delete [] array; return array[argc]; // BOOM } # Compile and link % clang -O1 -g -fsanitize=address -fno-omit-frame-pointer example_UseAfterFree.cc or: .. code-block:: console # Compile % clang -O1 -g -fsanitize=address -fno-omit-frame-pointer -c example_UseAfterFree.cc # Link % clang -g -fsanitize=address example_UseAfterFree.o If a bug is detected, the program will print an error message to stderr and exit with a non-zero exit code. To make AddressSanitizer symbolize its output you need to set the ``ASAN_SYMBOLIZER_PATH`` environment variable to point to the ``llvm-symbolizer`` binary (or make sure ``llvm-symbolizer`` is in your ``$PATH``): .. code-block:: console % ASAN_SYMBOLIZER_PATH=/usr/local/bin/llvm-symbolizer ./a.out ==9442== ERROR: AddressSanitizer heap-use-after-free on address 0x7f7ddab8c084 at pc 0x403c8c bp 0x7fff87fb82d0 sp 0x7fff87fb82c8 READ of size 4 at 0x7f7ddab8c084 thread T0 #0 0x403c8c in main example_UseAfterFree.cc:4 #1 0x7f7ddabcac4d in __libc_start_main ??:0 0x7f7ddab8c084 is located 4 bytes inside of 400-byte region [0x7f7ddab8c080,0x7f7ddab8c210) freed by thread T0 here: #0 0x404704 in operator delete[](void*) ??:0 #1 0x403c53 in main example_UseAfterFree.cc:4 #2 0x7f7ddabcac4d in __libc_start_main ??:0 previously allocated by thread T0 here: #0 0x404544 in operator new[](unsigned long) ??:0 #1 0x403c43 in main example_UseAfterFree.cc:2 #2 0x7f7ddabcac4d in __libc_start_main ??:0 ==9442== ABORTING If that does not work for you (e.g. your process is sandboxed), you can use a separate script to symbolize the result offline (online symbolization can be force disabled by setting ``ASAN_OPTIONS=symbolize=0``): .. code-block:: console % ASAN_OPTIONS=symbolize=0 ./a.out 2> log % projects/compiler-rt/lib/asan/scripts/asan_symbolize.py / < log | c++filt ==9442== ERROR: AddressSanitizer heap-use-after-free on address 0x7f7ddab8c084 at pc 0x403c8c bp 0x7fff87fb82d0 sp 0x7fff87fb82c8 READ of size 4 at 0x7f7ddab8c084 thread T0 #0 0x403c8c in main example_UseAfterFree.cc:4 #1 0x7f7ddabcac4d in __libc_start_main ??:0 ... Note that on OS X you may need to run ``dsymutil`` on your binary to have the file\:line info in the AddressSanitizer reports. AddressSanitizer exits on the first detected error. This is by design. One reason: it makes the generated code smaller and faster (both by ~5%). Another reason: this makes fixing bugs unavoidable. With Valgrind, it is often the case that users treat Valgrind warnings as false positives (which they are not) and don't fix them. ``__has_feature(address_sanitizer)`` ------------------------------------ In some cases one may need to execute different code depending on whether AddressSanitizer is enabled. :ref:`\_\_has\_feature ` can be used for this purpose. .. code-block:: c #if defined(__has_feature) # if __has_feature(address_sanitizer) // code that builds only under AddressSanitizer # endif #endif ``__attribute__((no_sanitize_address))`` ----------------------------------------------- Some code should not be instrumented by AddressSanitizer. One may use the function attribute :ref:`no_sanitize_address ` (or a deprecated synonym `no_address_safety_analysis`) to disable instrumentation of a particular function. This attribute may not be supported by other compilers, so we suggest to use it together with ``__has_feature(address_sanitizer)``. Initialization order checking ----------------------------- AddressSanitizer can optionally detect dynamic initialization order problems, when initialization of globals defined in one translation unit uses globals defined in another translation unit. To enable this check at runtime, you should set environment variable ``ASAN_OPTIONS=check_initialization_order=1``. Blacklist --------- AddressSanitizer supports ``src`` and ``fun`` entity types in :doc:`SanitizerSpecialCaseList`, that can be used to suppress error reports in the specified source files or functions. Additionally, AddressSanitizer introduces ``global`` and ``type`` entity types that can be used to suppress error reports for out-of-bound access to globals with certain names and types (you may only specify class or struct types). You may use an ``init`` category to suppress reports about initialization-order problems happening in certain source files or with certain global variables. .. code-block:: bash # Suppress error reports for code in a file or in a function: src:bad_file.cpp # Ignore all functions with names containing MyFooBar: fun:*MyFooBar* # Disable out-of-bound checks for global: global:bad_array # Disable out-of-bound checks for global instances of a given class ... type:class.Namespace::BadClassName # ... or a given struct. Use wildcard to deal with anonymous namespace. type:struct.Namespace2::*::BadStructName # Disable initialization-order checks for globals: global:bad_init_global=init type:*BadInitClassSubstring*=init src:bad/init/files/*=init Memory leak detection --------------------- For the experimental memory leak detector in AddressSanitizer, see :doc:`LeakSanitizer`. Supported Platforms =================== AddressSanitizer is supported on * Linux i386/x86\_64 (tested on Ubuntu 12.04); * MacOS 10.6 - 10.9 (i386/x86\_64). * Android ARM Ports to various other platforms are in progress. Limitations =========== * AddressSanitizer uses more real memory than a native run. Exact overhead depends on the allocations sizes. The smaller the allocations you make the bigger the overhead is. * AddressSanitizer uses more stack memory. We have seen up to 3x increase. * On 64-bit platforms AddressSanitizer maps (but not reserves) 16+ Terabytes of virtual address space. This means that tools like ``ulimit`` may not work as usually expected. * Static linking is not supported. Current Status ============== AddressSanitizer is fully functional on supported platforms starting from LLVM 3.1. The test suite is integrated into CMake build and can be run with ``make check-asan`` command. More Information ================ `http://code.google.com/p/address-sanitizer `_ @ 1.1.1.3.4.1 log @file AddressSanitizer.rst was added on branch yamt-pagecache on 2014-05-22 16:18:18 +0000 @ text @d1 216 @ 1.1.1.3.4.2 log @sync with head. for a reference, the tree before this commit was tagged as yamt-pagecache-tag8. this commit was splitted into small chunks to avoid a limitation of cvs. ("Protocol error: too many arguments") @ text @a0 216 ================ AddressSanitizer ================ .. contents:: :local: Introduction ============ AddressSanitizer is a fast memory error detector. It consists of a compiler instrumentation module and a run-time library. The tool can detect the following types of bugs: * Out-of-bounds accesses to heap, stack and globals * Use-after-free * Use-after-return (to some extent) * Double-free, invalid free * Memory leaks (experimental) Typical slowdown introduced by AddressSanitizer is **2x**. How to build ============ Follow the `clang build instructions <../get_started.html>`_. CMake build is supported. Usage ===== Simply compile and link your program with ``-fsanitize=address`` flag. The AddressSanitizer run-time library should be linked to the final executable, so make sure to use ``clang`` (not ``ld``) for the final link step. When linking shared libraries, the AddressSanitizer run-time is not linked, so ``-Wl,-z,defs`` may cause link errors (don't use it with AddressSanitizer). To get a reasonable performance add ``-O1`` or higher. To get nicer stack traces in error messages add ``-fno-omit-frame-pointer``. To get perfect stack traces you may need to disable inlining (just use ``-O1``) and tail call elimination (``-fno-optimize-sibling-calls``). .. code-block:: console % cat example_UseAfterFree.cc int main(int argc, char **argv) { int *array = new int[100]; delete [] array; return array[argc]; // BOOM } # Compile and link % clang -O1 -g -fsanitize=address -fno-omit-frame-pointer example_UseAfterFree.cc or: .. code-block:: console # Compile % clang -O1 -g -fsanitize=address -fno-omit-frame-pointer -c example_UseAfterFree.cc # Link % clang -g -fsanitize=address example_UseAfterFree.o If a bug is detected, the program will print an error message to stderr and exit with a non-zero exit code. To make AddressSanitizer symbolize its output you need to set the ``ASAN_SYMBOLIZER_PATH`` environment variable to point to the ``llvm-symbolizer`` binary (or make sure ``llvm-symbolizer`` is in your ``$PATH``): .. code-block:: console % ASAN_SYMBOLIZER_PATH=/usr/local/bin/llvm-symbolizer ./a.out ==9442== ERROR: AddressSanitizer heap-use-after-free on address 0x7f7ddab8c084 at pc 0x403c8c bp 0x7fff87fb82d0 sp 0x7fff87fb82c8 READ of size 4 at 0x7f7ddab8c084 thread T0 #0 0x403c8c in main example_UseAfterFree.cc:4 #1 0x7f7ddabcac4d in __libc_start_main ??:0 0x7f7ddab8c084 is located 4 bytes inside of 400-byte region [0x7f7ddab8c080,0x7f7ddab8c210) freed by thread T0 here: #0 0x404704 in operator delete[](void*) ??:0 #1 0x403c53 in main example_UseAfterFree.cc:4 #2 0x7f7ddabcac4d in __libc_start_main ??:0 previously allocated by thread T0 here: #0 0x404544 in operator new[](unsigned long) ??:0 #1 0x403c43 in main example_UseAfterFree.cc:2 #2 0x7f7ddabcac4d in __libc_start_main ??:0 ==9442== ABORTING If that does not work for you (e.g. your process is sandboxed), you can use a separate script to symbolize the result offline (online symbolization can be force disabled by setting ``ASAN_OPTIONS=symbolize=0``): .. code-block:: console % ASAN_OPTIONS=symbolize=0 ./a.out 2> log % projects/compiler-rt/lib/asan/scripts/asan_symbolize.py / < log | c++filt ==9442== ERROR: AddressSanitizer heap-use-after-free on address 0x7f7ddab8c084 at pc 0x403c8c bp 0x7fff87fb82d0 sp 0x7fff87fb82c8 READ of size 4 at 0x7f7ddab8c084 thread T0 #0 0x403c8c in main example_UseAfterFree.cc:4 #1 0x7f7ddabcac4d in __libc_start_main ??:0 ... Note that on OS X you may need to run ``dsymutil`` on your binary to have the file\:line info in the AddressSanitizer reports. AddressSanitizer exits on the first detected error. This is by design. One reason: it makes the generated code smaller and faster (both by ~5%). Another reason: this makes fixing bugs unavoidable. With Valgrind, it is often the case that users treat Valgrind warnings as false positives (which they are not) and don't fix them. ``__has_feature(address_sanitizer)`` ------------------------------------ In some cases one may need to execute different code depending on whether AddressSanitizer is enabled. :ref:`\_\_has\_feature ` can be used for this purpose. .. code-block:: c #if defined(__has_feature) # if __has_feature(address_sanitizer) // code that builds only under AddressSanitizer # endif #endif ``__attribute__((no_sanitize_address))`` ----------------------------------------------- Some code should not be instrumented by AddressSanitizer. One may use the function attribute :ref:`no_sanitize_address ` (or a deprecated synonym `no_address_safety_analysis`) to disable instrumentation of a particular function. This attribute may not be supported by other compilers, so we suggest to use it together with ``__has_feature(address_sanitizer)``. Initialization order checking ----------------------------- AddressSanitizer can optionally detect dynamic initialization order problems, when initialization of globals defined in one translation unit uses globals defined in another translation unit. To enable this check at runtime, you should set environment variable ``ASAN_OPTIONS=check_initialization_order=1``. Blacklist --------- AddressSanitizer supports ``src`` and ``fun`` entity types in :doc:`SanitizerSpecialCaseList`, that can be used to suppress error reports in the specified source files or functions. Additionally, AddressSanitizer introduces ``global`` and ``type`` entity types that can be used to suppress error reports for out-of-bound access to globals with certain names and types (you may only specify class or struct types). You may use an ``init`` category to suppress reports about initialization-order problems happening in certain source files or with certain global variables. .. code-block:: bash # Suppress error reports for code in a file or in a function: src:bad_file.cpp # Ignore all functions with names containing MyFooBar: fun:*MyFooBar* # Disable out-of-bound checks for global: global:bad_array # Disable out-of-bound checks for global instances of a given class ... type:class.Namespace::BadClassName # ... or a given struct. Use wildcard to deal with anonymous namespace. type:struct.Namespace2::*::BadStructName # Disable initialization-order checks for globals: global:bad_init_global=init type:*BadInitClassSubstring*=init src:bad/init/files/*=init Memory leak detection --------------------- For the experimental memory leak detector in AddressSanitizer, see :doc:`LeakSanitizer`. Supported Platforms =================== AddressSanitizer is supported on * Linux i386/x86\_64 (tested on Ubuntu 12.04); * MacOS 10.6 - 10.9 (i386/x86\_64). * Android ARM Ports to various other platforms are in progress. Limitations =========== * AddressSanitizer uses more real memory than a native run. Exact overhead depends on the allocations sizes. The smaller the allocations you make the bigger the overhead is. * AddressSanitizer uses more stack memory. We have seen up to 3x increase. * On 64-bit platforms AddressSanitizer maps (but not reserves) 16+ Terabytes of virtual address space. This means that tools like ``ulimit`` may not work as usually expected. * Static linking is not supported. Current Status ============== AddressSanitizer is fully functional on supported platforms starting from LLVM 3.1. The test suite is integrated into CMake build and can be run with ``make check-asan`` command. More Information ================ `http://code.google.com/p/address-sanitizer `_ @