1========================== 2UndefinedBehaviorSanitizer 3========================== 4 5.. contents:: 6 :local: 7 8Introduction 9============ 10 11UndefinedBehaviorSanitizer (UBSan) is a fast undefined behavior detector. 12UBSan modifies the program at compile-time to catch various kinds of undefined 13behavior 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 20See the full list of available :ref:`checks <ubsan-checks>` below. 21 22UBSan has an optional run-time library which provides better error reporting. 23The checks have small runtime cost and no impact on address space layout or ABI. 24 25How to build 26============ 27 28Build LLVM/Clang with `CMake <https://llvm.org/docs/CMake.html>`_. 29 30Usage 31===== 32 33Use ``clang++`` to compile and link your program with ``-fsanitize=undefined`` 34flag. Make sure to use ``clang++`` (not ``ld``) as a linker, so that your 35executable is linked with proper UBSan runtime libraries. You can use ``clang`` 36instead 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 50You can enable only a subset of :ref:`checks <ubsan-checks>` offered by UBSan, 51and define the desired behavior for each kind of check: 52 53* ``-fsanitize=...``: print a verbose error report and continue execution (default); 54* ``-fno-sanitize-recover=...``: print a verbose error report and exit the program; 55* ``-fsanitize-trap=...``: execute a trap instruction (doesn't require UBSan run-time support). 56 57Note that the ``trap`` / ``recover`` options do not enable the corresponding 58sanitizer, and in general need to be accompanied by a suitable ``-fsanitize=`` 59flag. 60 61For example if you compile/link your program as: 62 63.. code-block:: console 64 65 % clang++ -fsanitize=signed-integer-overflow,null,alignment -fno-sanitize-recover=null -fsanitize-trap=alignment 66 67the program will continue execution after signed integer overflows, exit after 68the first invalid use of a null pointer, and trap after the first use of misaligned 69pointer. 70 71.. _ubsan-checks: 72 73Available checks 74================ 75 76Available checks are: 77 78 - ``-fsanitize=alignment``: Use of a misaligned pointer or creation 79 of a misaligned reference. Also sanitizes assume_aligned-like attributes. 80 - ``-fsanitize=bool``: Load of a ``bool`` value which is neither 81 ``true`` nor ``false``. 82 - ``-fsanitize=builtin``: Passing invalid values to compiler builtins. 83 - ``-fsanitize=bounds``: Out of bounds array indexing, in cases 84 where the array bound can be statically determined. The check includes 85 ``-fsanitize=array-bounds`` and ``-fsanitize=local-bounds``. Note that 86 ``-fsanitize=local-bounds`` is not included in ``-fsanitize=undefined``. 87 - ``-fsanitize=enum``: Load of a value of an enumerated type which 88 is not in the range of representable values for that enumerated 89 type. 90 - ``-fsanitize=float-cast-overflow``: Conversion to, from, or 91 between floating-point types which would overflow the 92 destination. Because the range of representable values for all 93 floating-point types supported by Clang is [-inf, +inf], the only 94 cases detected are conversions from floating point to integer types. 95 - ``-fsanitize=float-divide-by-zero``: Floating point division by 96 zero. This is undefined per the C and C++ standards, but is defined 97 by Clang (and by ISO/IEC/IEEE 60559 / IEEE 754) as producing either an 98 infinity or NaN value, so is not included in ``-fsanitize=undefined``. 99 - ``-fsanitize=function``: Indirect call of a function through a 100 function pointer of the wrong type (Darwin/Linux, C++ and x86/x86_64 101 only). 102 - ``-fsanitize=implicit-unsigned-integer-truncation``, 103 ``-fsanitize=implicit-signed-integer-truncation``: Implicit conversion from 104 integer of larger bit width to smaller bit width, if that results in data 105 loss. That is, if the demoted value, after casting back to the original 106 width, is not equal to the original value before the downcast. 107 The ``-fsanitize=implicit-unsigned-integer-truncation`` handles conversions 108 between two ``unsigned`` types, while 109 ``-fsanitize=implicit-signed-integer-truncation`` handles the rest of the 110 conversions - when either one, or both of the types are signed. 111 Issues caught by these sanitizers are not undefined behavior, 112 but are often unintentional. 113 - ``-fsanitize=implicit-integer-sign-change``: Implicit conversion between 114 integer types, if that changes the sign of the value. That is, if the the 115 original value was negative and the new value is positive (or zero), 116 or the original value was positive, and the new value is negative. 117 Issues caught by this sanitizer are not undefined behavior, 118 but are often unintentional. 119 - ``-fsanitize=integer-divide-by-zero``: Integer division by zero. 120 - ``-fsanitize=nonnull-attribute``: Passing null pointer as a function 121 parameter which is declared to never be null. 122 - ``-fsanitize=null``: Use of a null pointer or creation of a null 123 reference. 124 - ``-fsanitize=nullability-arg``: Passing null as a function parameter 125 which is annotated with ``_Nonnull``. 126 - ``-fsanitize=nullability-assign``: Assigning null to an lvalue which 127 is annotated with ``_Nonnull``. 128 - ``-fsanitize=nullability-return``: Returning null from a function with 129 a return type annotated with ``_Nonnull``. 130 - ``-fsanitize=objc-cast``: Invalid implicit cast of an ObjC object pointer 131 to an incompatible type. This is often unintentional, but is not undefined 132 behavior, therefore the check is not a part of the ``undefined`` group. 133 Currently only supported on Darwin. 134 - ``-fsanitize=object-size``: An attempt to potentially use bytes which 135 the optimizer can determine are not part of the object being accessed. 136 This will also detect some types of undefined behavior that may not 137 directly access memory, but are provably incorrect given the size of 138 the objects involved, such as invalid downcasts and calling methods on 139 invalid pointers. These checks are made in terms of 140 ``__builtin_object_size``, and consequently may be able to detect more 141 problems at higher optimization levels. 142 - ``-fsanitize=pointer-overflow``: Performing pointer arithmetic which 143 overflows, or where either the old or new pointer value is a null pointer 144 (or in C, when they both are). 145 - ``-fsanitize=return``: In C++, reaching the end of a 146 value-returning function without returning a value. 147 - ``-fsanitize=returns-nonnull-attribute``: Returning null pointer 148 from a function which is declared to never return null. 149 - ``-fsanitize=shift``: Shift operators where the amount shifted is 150 greater or equal to the promoted bit-width of the left hand side 151 or less than zero, or where the left hand side is negative. For a 152 signed left shift, also checks for signed overflow in C, and for 153 unsigned overflow in C++. You can use ``-fsanitize=shift-base`` or 154 ``-fsanitize=shift-exponent`` to check only left-hand side or 155 right-hand side of shift operation, respectively. 156 - ``-fsanitize=signed-integer-overflow``: Signed integer overflow, where the 157 result of a signed integer computation cannot be represented in its type. 158 This includes all the checks covered by ``-ftrapv``, as well as checks for 159 signed division overflow (``INT_MIN/-1``), but not checks for 160 lossy implicit conversions performed before the computation 161 (see ``-fsanitize=implicit-conversion``). Both of these two issues are 162 handled by ``-fsanitize=implicit-conversion`` group of checks. 163 - ``-fsanitize=unreachable``: If control flow reaches an unreachable 164 program point. 165 - ``-fsanitize=unsigned-integer-overflow``: Unsigned integer overflow, where 166 the result of an unsigned integer computation cannot be represented in its 167 type. Unlike signed integer overflow, this is not undefined behavior, but 168 it is often unintentional. This sanitizer does not check for lossy implicit 169 conversions performed before such a computation 170 (see ``-fsanitize=implicit-conversion``). 171 - ``-fsanitize=vla-bound``: A variable-length array whose bound 172 does not evaluate to a positive value. 173 - ``-fsanitize=vptr``: Use of an object whose vptr indicates that it is of 174 the wrong dynamic type, or that its lifetime has not begun or has ended. 175 Incompatible with ``-fno-rtti``. Link must be performed by ``clang++``, not 176 ``clang``, to make sure C++-specific parts of the runtime library and C++ 177 standard libraries are present. 178 179You can also use the following check groups: 180 - ``-fsanitize=undefined``: All of the checks listed above other than 181 ``float-divide-by-zero``, ``unsigned-integer-overflow``, 182 ``implicit-conversion``, ``local-bounds`` and the ``nullability-*`` group 183 of checks. 184 - ``-fsanitize=undefined-trap``: Deprecated alias of 185 ``-fsanitize=undefined``. 186 - ``-fsanitize=implicit-integer-truncation``: Catches lossy integral 187 conversions. Enables ``implicit-signed-integer-truncation`` and 188 ``implicit-unsigned-integer-truncation``. 189 - ``-fsanitize=implicit-integer-arithmetic-value-change``: Catches implicit 190 conversions that change the arithmetic value of the integer. Enables 191 ``implicit-signed-integer-truncation`` and ``implicit-integer-sign-change``. 192 - ``-fsanitize=implicit-conversion``: Checks for suspicious 193 behavior of implicit conversions. Enables 194 ``implicit-unsigned-integer-truncation``, 195 ``implicit-signed-integer-truncation``, and 196 ``implicit-integer-sign-change``. 197 - ``-fsanitize=integer``: Checks for undefined or suspicious integer 198 behavior (e.g. unsigned integer overflow). 199 Enables ``signed-integer-overflow``, ``unsigned-integer-overflow``, 200 ``shift``, ``integer-divide-by-zero``, 201 ``implicit-unsigned-integer-truncation``, 202 ``implicit-signed-integer-truncation``, and 203 ``implicit-integer-sign-change``. 204 - ``-fsanitize=nullability``: Enables ``nullability-arg``, 205 ``nullability-assign``, and ``nullability-return``. While violating 206 nullability does not have undefined behavior, it is often unintentional, 207 so UBSan offers to catch it. 208 209Volatile 210-------- 211 212The ``null``, ``alignment``, ``object-size``, ``local-bounds``, and ``vptr`` checks do not apply 213to pointers to types with the ``volatile`` qualifier. 214 215Minimal Runtime 216=============== 217 218There is a minimal UBSan runtime available suitable for use in production 219environments. This runtime has a small attack surface. It only provides very 220basic issue logging and deduplication, and does not support 221``-fsanitize=function`` and ``-fsanitize=vptr`` checking. 222 223To use the minimal runtime, add ``-fsanitize-minimal-runtime`` to the clang 224command line options. For example, if you're used to compiling with 225``-fsanitize=undefined``, you could enable the minimal runtime with 226``-fsanitize=undefined -fsanitize-minimal-runtime``. 227 228Stack traces and report symbolization 229===================================== 230If you want UBSan to print symbolized stack trace for each error report, you 231will need to: 232 233#. Compile with ``-g`` and ``-fno-omit-frame-pointer`` to get proper debug 234 information in your binary. 235#. Run your program with environment variable 236 ``UBSAN_OPTIONS=print_stacktrace=1``. 237#. Make sure ``llvm-symbolizer`` binary is in ``PATH``. 238 239Logging 240======= 241 242The default log file for diagnostics is "stderr". To log diagnostics to another 243file, you can set ``UBSAN_OPTIONS=log_path=...``. 244 245Silencing Unsigned Integer Overflow 246=================================== 247To silence reports from unsigned integer overflow, you can set 248``UBSAN_OPTIONS=silence_unsigned_overflow=1``. This feature, combined with 249``-fsanitize-recover=unsigned-integer-overflow``, is particularly useful for 250providing fuzzing signal without blowing up logs. 251 252Issue Suppression 253================= 254 255UndefinedBehaviorSanitizer is not expected to produce false positives. 256If you see one, look again; most likely it is a true positive! 257 258Disabling Instrumentation with ``__attribute__((no_sanitize("undefined")))`` 259---------------------------------------------------------------------------- 260 261You disable UBSan checks for particular functions with 262``__attribute__((no_sanitize("undefined")))``. You can use all values of 263``-fsanitize=`` flag in this attribute, e.g. if your function deliberately 264contains possible signed integer overflow, you can use 265``__attribute__((no_sanitize("signed-integer-overflow")))``. 266 267This attribute may not be 268supported by other compilers, so consider using it together with 269``#if defined(__clang__)``. 270 271Suppressing Errors in Recompiled Code (Blacklist) 272------------------------------------------------- 273 274UndefinedBehaviorSanitizer supports ``src`` and ``fun`` entity types in 275:doc:`SanitizerSpecialCaseList`, that can be used to suppress error reports 276in the specified source files or functions. 277 278Runtime suppressions 279-------------------- 280 281Sometimes you can suppress UBSan error reports for specific files, functions, 282or libraries without recompiling the code. You need to pass a path to 283suppression file in a ``UBSAN_OPTIONS`` environment variable. 284 285.. code-block:: bash 286 287 UBSAN_OPTIONS=suppressions=MyUBSan.supp 288 289You need to specify a :ref:`check <ubsan-checks>` you are suppressing and the 290bug location. For example: 291 292.. code-block:: bash 293 294 signed-integer-overflow:file-with-known-overflow.cpp 295 alignment:function_doing_unaligned_access 296 vptr:shared_object_with_vptr_failures.so 297 298There are several limitations: 299 300* Sometimes your binary must have enough debug info and/or symbol table, so 301 that the runtime could figure out source file or function name to match 302 against the suppression. 303* It is only possible to suppress recoverable checks. For the example above, 304 you can additionally pass 305 ``-fsanitize-recover=signed-integer-overflow,alignment,vptr``, although 306 most of UBSan checks are recoverable by default. 307* Check groups (like ``undefined``) can't be used in suppressions file, only 308 fine-grained checks are supported. 309 310Supported Platforms 311=================== 312 313UndefinedBehaviorSanitizer is supported on the following operating systems: 314 315* Android 316* Linux 317* NetBSD 318* FreeBSD 319* OpenBSD 320* macOS 321* Windows 322 323The runtime library is relatively portable and platform independent. If the OS 324you need is not listed above, UndefinedBehaviorSanitizer may already work for 325it, or could be made to work with a minor porting effort. 326 327Current Status 328============== 329 330UndefinedBehaviorSanitizer is available on selected platforms starting from LLVM 3313.3. The test suite is integrated into the CMake build and can be run with 332``check-ubsan`` command. 333 334Additional Configuration 335======================== 336 337UndefinedBehaviorSanitizer adds static check data for each check unless it is 338in trap mode. This check data includes the full file name. The option 339``-fsanitize-undefined-strip-path-components=N`` can be used to trim this 340information. If ``N`` is positive, file information emitted by 341UndefinedBehaviorSanitizer will drop the first ``N`` components from the file 342path. If ``N`` is negative, the last ``N`` components will be kept. 343 344Example 345------- 346 347For a file called ``/code/library/file.cpp``, here is what would be emitted: 348 349* Default (No flag, or ``-fsanitize-undefined-strip-path-components=0``): ``/code/library/file.cpp`` 350* ``-fsanitize-undefined-strip-path-components=1``: ``code/library/file.cpp`` 351* ``-fsanitize-undefined-strip-path-components=2``: ``library/file.cpp`` 352* ``-fsanitize-undefined-strip-path-components=-1``: ``file.cpp`` 353* ``-fsanitize-undefined-strip-path-components=-2``: ``library/file.cpp`` 354 355More Information 356================ 357 358* From LLVM project blog: 359 `What Every C Programmer Should Know About Undefined Behavior 360 <http://blog.llvm.org/2011/05/what-every-c-programmer-should-know.html>`_ 361* From John Regehr's *Embedded in Academia* blog: 362 `A Guide to Undefined Behavior in C and C++ 363 <https://blog.regehr.org/archives/213>`_ 364