1 ========================== 2 UndefinedBehaviorSanitizer 3 ========================== 4 5 .. contents:: 6 :local: 7 8 Introduction 9 ============ 10 11 UndefinedBehaviorSanitizer (UBSan) is a fast undefined behavior detector. 12 UBSan modifies the program at compile-time to catch various kinds of undefined 13 behavior during program execution, for example: 14 15 * Using misaligned or null pointer 16 * Signed integer overflow 17 * Conversion to, from, or between floating-point types which would 18 overflow the destination 19 20 See the full list of available :ref:`checks <ubsan-checks>` below. 21 22 UBSan has an optional run-time library which provides better error reporting. 23 The checks have small runtime cost and no impact on address space layout or ABI. 24 25 How to build 26 ============ 27 28 Build LLVM/Clang with `CMake <http://llvm.org/docs/CMake.html>`_. 29 30 Usage 31 ===== 32 33 Use ``clang++`` to compile and link your program with ``-fsanitize=undefined`` 34 flag. Make sure to use ``clang++`` (not ``ld``) as a linker, so that your 35 executable is linked with proper UBSan runtime libraries. You can use ``clang`` 36 instead of ``clang++`` if you're compiling/linking C code. 37 38 .. code-block:: console 39 40 % cat test.cc 41 int main(int argc, char **argv) { 42 int k = 0x7fffffff; 43 k += argc; 44 return 0; 45 } 46 % clang++ -fsanitize=undefined test.cc 47 % ./a.out 48 test.cc:3:5: runtime error: signed integer overflow: 2147483647 + 1 cannot be represented in type 'int' 49 50 You can enable only a subset of :ref:`checks <ubsan-checks>` offered by UBSan, 51 and define the desired behavior for each kind of check: 52 53 * print a verbose error report and continue execution (default); 54 * print a verbose error report and exit the program; 55 * execute a trap instruction (doesn't require UBSan run-time support). 56 57 For example if you compile/link your program as: 58 59 .. code-block:: console 60 61 % clang++ -fsanitize=signed-integer-overflow,null,alignment -fno-sanitize-recover=null -fsanitize-trap=alignment 62 63 the program will continue execution after signed integer overflows, exit after 64 the first invalid use of a null pointer, and trap after the first use of misaligned 65 pointer. 66 67 .. _ubsan-checks: 68 69 Availablle checks 70 ================= 71 72 Available checks are: 73 74 - ``-fsanitize=alignment``: Use of a misaligned pointer or creation 75 of a misaligned reference. 76 - ``-fsanitize=bool``: Load of a ``bool`` value which is neither 77 ``true`` nor ``false``. 78 - ``-fsanitize=bounds``: Out of bounds array indexing, in cases 79 where the array bound can be statically determined. 80 - ``-fsanitize=enum``: Load of a value of an enumerated type which 81 is not in the range of representable values for that enumerated 82 type. 83 - ``-fsanitize=float-cast-overflow``: Conversion to, from, or 84 between floating-point types which would overflow the 85 destination. 86 - ``-fsanitize=float-divide-by-zero``: Floating point division by 87 zero. 88 - ``-fsanitize=function``: Indirect call of a function through a 89 function pointer of the wrong type (Linux, C++ and x86/x86_64 only). 90 - ``-fsanitize=integer-divide-by-zero``: Integer division by zero. 91 - ``-fsanitize=nonnull-attribute``: Passing null pointer as a function 92 parameter which is declared to never be null. 93 - ``-fsanitize=null``: Use of a null pointer or creation of a null 94 reference. 95 - ``-fsanitize=object-size``: An attempt to potentially use bytes which 96 the optimizer can determine are not part of the object being accessed. 97 This will also detect some types of undefined behavior that may not 98 directly access memory, but are provably incorrect given the size of 99 the objects involved, such as invalid downcasts and calling methods on 100 invalid pointers. These checks are made in terms of 101 ``__builtin_object_size``, and consequently may be able to detect more 102 problems at higher optimization levels. 103 - ``-fsanitize=return``: In C++, reaching the end of a 104 value-returning function without returning a value. 105 - ``-fsanitize=returns-nonnull-attribute``: Returning null pointer 106 from a function which is declared to never return null. 107 - ``-fsanitize=shift``: Shift operators where the amount shifted is 108 greater or equal to the promoted bit-width of the left hand side 109 or less than zero, or where the left hand side is negative. For a 110 signed left shift, also checks for signed overflow in C, and for 111 unsigned overflow in C++. You can use ``-fsanitize=shift-base`` or 112 ``-fsanitize=shift-exponent`` to check only left-hand side or 113 right-hand side of shift operation, respectively. 114 - ``-fsanitize=signed-integer-overflow``: Signed integer overflow, 115 including all the checks added by ``-ftrapv``, and checking for 116 overflow in signed division (``INT_MIN / -1``). 117 - ``-fsanitize=unreachable``: If control flow reaches 118 ``__builtin_unreachable``. 119 - ``-fsanitize=unsigned-integer-overflow``: Unsigned integer 120 overflows. 121 - ``-fsanitize=vla-bound``: A variable-length array whose bound 122 does not evaluate to a positive value. 123 - ``-fsanitize=vptr``: Use of an object whose vptr indicates that 124 it is of the wrong dynamic type, or that its lifetime has not 125 begun or has ended. Incompatible with ``-fno-rtti``. Link must 126 be performed by ``clang++``, not ``clang``, to make sure C++-specific 127 parts of the runtime library and C++ standard libraries are present. 128 129 You can also use the following check groups: 130 - ``-fsanitize=undefined``: All of the checks listed above other than 131 ``unsigned-integer-overflow``. 132 - ``-fsanitize=undefined-trap``: Deprecated alias of 133 ``-fsanitize=undefined``. 134 - ``-fsanitize=integer``: Checks for undefined or suspicious integer 135 behavior (e.g. unsigned integer overflow). 136 137 Stack traces and report symbolization 138 ===================================== 139 If you want UBSan to print symbolized stack trace for each error report, you 140 will need to: 141 142 #. Compile with ``-g`` and ``-fno-omit-frame-pointer`` to get proper debug 143 information in your binary. 144 #. Run your program with environment variable 145 ``UBSAN_OPTIONS=print_stacktrace=1``. 146 #. Make sure ``llvm-symbolizer`` binary is in ``PATH``. 147 148 Issue Suppression 149 ================= 150 151 UndefinedBehaviorSanitizer is not expected to produce false positives. 152 If you see one, look again; most likely it is a true positive! 153 154 Disabling Instrumentation with ``__attribute__((no_sanitize("undefined")))`` 155 ---------------------------------------------------------------------------- 156 157 You disable UBSan checks for particular functions with 158 ``__attribute__((no_sanitize("undefined")))``. You can use all values of 159 ``-fsanitize=`` flag in this attribute, e.g. if your function deliberately 160 contains possible signed integer overflow, you can use 161 ``__attribute__((no_sanitize("signed-integer-overflow")))``. 162 163 This attribute may not be 164 supported by other compilers, so consider using it together with 165 ``#if defined(__clang__)``. 166 167 Suppressing Errors in Recompiled Code (Blacklist) 168 ------------------------------------------------- 169 170 UndefinedBehaviorSanitizer supports ``src`` and ``fun`` entity types in 171 :doc:`SanitizerSpecialCaseList`, that can be used to suppress error reports 172 in the specified source files or functions. 173 174 Runtime suppressions 175 -------------------- 176 177 Sometimes you can suppress UBSan error reports for specific files, functions, 178 or libraries without recompiling the code. You need to pass a path to 179 suppression file in a ``UBSAN_OPTIONS`` environment variable. 180 181 .. code-block:: bash 182 183 UBSAN_OPTIONS=suppressions=MyUBSan.supp 184 185 You need to specify a :ref:`check <ubsan-checks>` you are suppressing and the 186 bug location. For example: 187 188 .. code-block:: bash 189 190 signed-integer-overflow:file-with-known-overflow.cpp 191 alignment:function_doing_unaligned_access 192 vptr:shared_object_with_vptr_failures.so 193 194 There are several limitations: 195 196 * Sometimes your binary must have enough debug info and/or symbol table, so 197 that the runtime could figure out source file or function name to match 198 against the suppression. 199 * It is only possible to suppress recoverable checks. For the example above, 200 you can additionally pass 201 ``-fsanitize-recover=signed-integer-overflow,alignment,vptr``, although 202 most of UBSan checks are recoverable by default. 203 * Check groups (like ``undefined``) can't be used in suppressions file, only 204 fine-grained checks are supported. 205 206 Supported Platforms 207 =================== 208 209 UndefinedBehaviorSanitizer is supported on the following OS: 210 211 * Android 212 * Linux 213 * FreeBSD 214 * OS X 10.6 onwards 215 216 and for the following architectures: 217 218 * i386/x86\_64 219 * ARM 220 * AArch64 221 * PowerPC64 222 * MIPS/MIPS64 223 224 Current Status 225 ============== 226 227 UndefinedBehaviorSanitizer is available on selected platforms starting from LLVM 228 3.3. The test suite is integrated into the CMake build and can be run with 229 ``check-ubsan`` command. 230 231 Additional Configuration 232 ======================== 233 234 UndefinedBehaviorSanitizer adds static check data for each check unless it is 235 in trap mode. This check data includes the full file name. The option 236 ``-fsanitize-undefined-strip-path-components=N`` can be used to trim this 237 information. If ``N`` is positive, file information emitted by 238 UndefinedBehaviorSanitizer will drop the first ``N`` components from the file 239 path. If ``N`` is negative, the last ``N`` components will be kept. 240 241 Example 242 ------- 243 244 For a file called ``/code/library/file.cpp``, here is what would be emitted: 245 * Default (No flag, or ``-fsanitize-undefined-strip-path-components=0``): ``/code/library/file.cpp`` 246 * ``-fsanitize-undefined-strip-path-components=1``: ``code/library/file.cpp`` 247 * ``-fsanitize-undefined-strip-path-components=2``: ``library/file.cpp`` 248 * ``-fsanitize-undefined-strip-path-components=-1``: ``file.cpp`` 249 * ``-fsanitize-undefined-strip-path-components=-2``: ``library/file.cpp`` 250 251 More Information 252 ================ 253 254 * From LLVM project blog: 255 `What Every C Programmer Should Know About Undefined Behavior 256 <http://blog.llvm.org/2011/05/what-every-c-programmer-should-know.html>`_ 257 * From John Regehr's *Embedded in Academia* blog: 258 `A Guide to Undefined Behavior in C and C++ 259 <http://blog.regehr.org/archives/213>`_ 260
