1================ 2MemorySanitizer 3================ 4 5.. contents:: 6 :local: 7 8Introduction 9============ 10 11MemorySanitizer is a detector of uninitialized reads. It consists of a 12compiler instrumentation module and a run-time library. 13 14Typical slowdown introduced by MemorySanitizer is **3x**. 15 16How to build 17============ 18 19Follow the `clang build instructions <../get_started.html>`_. CMake 20build is supported. 21 22Usage 23===== 24 25Simply compile and link your program with ``-fsanitize=memory`` flag. 26The MemorySanitizer run-time library should be linked to the final 27executable, so make sure to use ``clang`` (not ``ld``) for the final 28link step. When linking shared libraries, the MemorySanitizer run-time 29is not linked, so ``-Wl,-z,defs`` may cause link errors (don't use it 30with MemorySanitizer). To get a reasonable performance add ``-O1`` or 31higher. To get meaninful stack traces in error messages add 32``-fno-omit-frame-pointer``. To get perfect stack traces you may need 33to disable inlining (just use ``-O1``) and tail call elimination 34(``-fno-optimize-sibling-calls``). 35 36.. code-block:: console 37 38 % cat umr.cc 39 #include <stdio.h> 40 41 int main(int argc, char** argv) { 42 int* a = new int[10]; 43 a[5] = 0; 44 if (a[argc]) 45 printf("xx\n"); 46 return 0; 47 } 48 49 % clang -fsanitize=memory -fno-omit-frame-pointer -g -O2 umr.cc 50 51If a bug is detected, the program will print an error message to 52stderr and exit with a non-zero exit code. Currently, MemorySanitizer 53does not symbolize its output by default, so you may need to use a 54separate script to symbolize the result offline (this will be fixed in 55future). 56 57.. code-block:: console 58 59 % ./a.out 2>log 60 % projects/compiler-rt/lib/asan/scripts/asan_symbolize.py / < log | c++filt 61 ==30106== WARNING: MemorySanitizer: UMR (uninitialized-memory-read) 62 #0 0x7f45944b418a in main umr.cc:6 63 #1 0x7f45938b676c in __libc_start_main libc-start.c:226 64 Exiting 65 66By default, MemorySanitizer exits on the first detected error. 67 68``__has_feature(memory_sanitizer)`` 69------------------------------------ 70 71In some cases one may need to execute different code depending on 72whether MemorySanitizer is enabled. :ref:`\_\_has\_feature 73<langext-__has_feature-__has_extension>` can be used for this purpose. 74 75.. code-block:: c 76 77 #if defined(__has_feature) 78 # if __has_feature(memory_sanitizer) 79 // code that builds only under MemorySanitizer 80 # endif 81 #endif 82 83``__attribute__((no_sanitize_memory))`` 84----------------------------------------------- 85 86Some code should not be checked by MemorySanitizer. 87One may use the function attribute 88:ref:`no_sanitize_memory <langext-memory_sanitizer>` 89to disable uninitialized checks in a particular function. 90MemorySanitizer may still instrument such functions to avoid false positives. 91This attribute may not be 92supported by other compilers, so we suggest to use it together with 93``__has_feature(memory_sanitizer)``. 94 95Blacklist 96--------- 97 98MemorySanitizer supports ``src`` and ``fun`` entity types in 99:doc:`SanitizerSpecialCaseList`, that can be used to relax MemorySanitizer 100checks for certain source files and functions. All "Use of uninitialized value" 101warnings will be suppressed and all values loaded from memory will be 102considered fully initialized. 103 104Origin Tracking 105=============== 106 107MemorySanitizer can track origins of unitialized values, similar to 108Valgrind's --track-origins option. This feature is enabled by 109``-fsanitize-memory-track-origins`` Clang option. With the code from 110the example above, 111 112.. code-block:: console 113 114 % clang -fsanitize=memory -fsanitize-memory-track-origins -fno-omit-frame-pointer -g -O2 umr.cc 115 % ./a.out 2>log 116 % projects/compiler-rt/lib/asan/scripts/asan_symbolize.py / < log | c++filt 117 ==14425== WARNING: MemorySanitizer: UMR (uninitialized-memory-read) 118 ==14425== WARNING: Trying to symbolize code, but external symbolizer is not initialized! 119 #0 0x7f8bdda3824b in main umr.cc:6 120 #1 0x7f8bdce3a76c in __libc_start_main libc-start.c:226 121 raw origin id: 2030043137 122 ORIGIN: heap allocation: 123 #0 0x7f8bdda4034b in operator new[](unsigned long) msan_new_delete.cc:39 124 #1 0x7f8bdda3814d in main umr.cc:4 125 #2 0x7f8bdce3a76c in __libc_start_main libc-start.c:226 126 Exiting 127 128Origin tracking has proved to be very useful for debugging UMR 129reports. It slows down program execution by a factor of 1.5x-2x on top 130of the usual MemorySanitizer slowdown. 131 132Handling external code 133============================ 134 135MemorySanitizer requires that all program code is instrumented. This 136also includes any libraries that the program depends on, even libc. 137Failing to achieve this may result in false UMR reports. 138 139Full MemorySanitizer instrumentation is very difficult to achieve. To 140make it easier, MemorySanitizer runtime library includes 70+ 141interceptors for the most common libc functions. They make it possible 142to run MemorySanitizer-instrumented programs linked with 143uninstrumented libc. For example, the authors were able to bootstrap 144MemorySanitizer-instrumented Clang compiler by linking it with 145self-built instrumented libcxx (as a replacement for libstdc++). 146 147In the case when rebuilding all program dependencies with 148MemorySanitizer is problematic, an experimental MSanDR tool can be 149used. It is a DynamoRio-based tool that uses dynamic instrumentation 150to avoid false positives due to uninstrumented code. The tool simply 151marks memory from instrumented libraries as fully initialized. See 152`http://code.google.com/p/memory-sanitizer/wiki/Running#Running_with_the_dynamic_tool` 153for more information. 154 155Supported Platforms 156=================== 157 158MemorySanitizer is supported on 159 160* Linux x86\_64 (tested on Ubuntu 10.04 and 12.04); 161 162Limitations 163=========== 164 165* MemorySanitizer uses 2x more real memory than a native run, 3x with 166 origin tracking. 167* MemorySanitizer maps (but not reserves) 64 Terabytes of virtual 168 address space. This means that tools like ``ulimit`` may not work as 169 usually expected. 170* Static linking is not supported. 171* Non-position-independent executables are not supported. Therefore, the 172 ``fsanitize=memory`` flag will cause Clang to act as though the ``-fPIE`` 173 flag had been supplied if compiling without ``-fPIC``, and as though the 174 ``-pie`` flag had been supplied if linking an executable. 175* Depending on the version of Linux kernel, running without ASLR may 176 be not supported. Note that GDB disables ASLR by default. To debug 177 instrumented programs, use "set disable-randomization off". 178 179Current Status 180============== 181 182MemorySanitizer is an experimental tool. It is known to work on large 183real-world programs, like Clang/LLVM itself. 184 185More Information 186================ 187 188`http://code.google.com/p/memory-sanitizer <http://code.google.com/p/memory-sanitizer/>`_ 189 190