docs/UndefinedBehaviorSanitizer.rst

   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 * ``-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
  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 Available 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=builtin``: Passing invalid values to compiler builtins.
  79   -  ``-fsanitize=bounds``: Out of bounds array indexing, in cases
  80      where the array bound can be statically determined.
  81   -  ``-fsanitize=enum``: Load of a value of an enumerated type which
  82      is not in the range of representable values for that enumerated
  83      type.
  84   -  ``-fsanitize=float-cast-overflow``: Conversion to, from, or
  85      between floating-point types which would overflow the
  86      destination.
  87   -  ``-fsanitize=float-divide-by-zero``: Floating point division by
  88      zero.
  89   -  ``-fsanitize=function``: Indirect call of a function through a
  90      function pointer of the wrong type (Darwin/Linux, C++ and x86/x86_64
  91      only).
  92   -  ``-fsanitize=integer-divide-by-zero``: Integer division by zero.
  93   -  ``-fsanitize=nonnull-attribute``: Passing null pointer as a function
  94      parameter which is declared to never be null.
  95   -  ``-fsanitize=null``: Use of a null pointer or creation of a null
  96      reference.
  97   -  ``-fsanitize=nullability-arg``: Passing null as a function parameter
  98      which is annotated with ``_Nonnull``.
  99   -  ``-fsanitize=nullability-assign``: Assigning null to an lvalue which
 100      is annotated with ``_Nonnull``.
 101   -  ``-fsanitize=nullability-return``: Returning null from a function with
 102      a return type annotated with ``_Nonnull``.
 103   -  ``-fsanitize=object-size``: An attempt to potentially use bytes which
 104      the optimizer can determine are not part of the object being accessed.
 105      This will also detect some types of undefined behavior that may not
 106      directly access memory, but are provably incorrect given the size of
 107      the objects involved, such as invalid downcasts and calling methods on
 108      invalid pointers. These checks are made in terms of
 109      ``__builtin_object_size``, and consequently may be able to detect more
 110      problems at higher optimization levels.
 111   -  ``-fsanitize=pointer-overflow``: Performing pointer arithmetic which
 112      overflows.
 113   -  ``-fsanitize=return``: In C++, reaching the end of a
 114      value-returning function without returning a value.
 115   -  ``-fsanitize=returns-nonnull-attribute``: Returning null pointer
 116      from a function which is declared to never return null.
 117   -  ``-fsanitize=shift``: Shift operators where the amount shifted is
 118      greater or equal to the promoted bit-width of the left hand side
 119      or less than zero, or where the left hand side is negative. For a
 120      signed left shift, also checks for signed overflow in C, and for
 121      unsigned overflow in C++. You can use ``-fsanitize=shift-base`` or
 122      ``-fsanitize=shift-exponent`` to check only left-hand side or
 123      right-hand side of shift operation, respectively.
 124   -  ``-fsanitize=signed-integer-overflow``: Signed integer overflow,
 125      including all the checks added by ``-ftrapv``, and checking for
 126      overflow in signed division (``INT_MIN / -1``).
 127   -  ``-fsanitize=unreachable``: If control flow reaches an unreachable
 128      program point.
 129   -  ``-fsanitize=unsigned-integer-overflow``: Unsigned integer
 130      overflows. Note that unlike signed integer overflow, unsigned integer
 131      is not undefined behavior. However, while it has well-defined semantics,
 132      it is often unintentional, so UBSan offers to catch it.
 133   -  ``-fsanitize=vla-bound``: A variable-length array whose bound
 134      does not evaluate to a positive value.
 135   -  ``-fsanitize=vptr``: Use of an object whose vptr indicates that it is of
 136      the wrong dynamic type, or that its lifetime has not begun or has ended.
 137      Incompatible with ``-fno-rtti``. Link must be performed by ``clang++``, not
 138      ``clang``, to make sure C++-specific parts of the runtime library and C++
 139      standard libraries are present.
 140
 141 You can also use the following check groups:
 142   -  ``-fsanitize=undefined``: All of the checks listed above other than
 143      ``unsigned-integer-overflow`` and the ``nullability-*`` checks.
 144   -  ``-fsanitize=undefined-trap``: Deprecated alias of
 145      ``-fsanitize=undefined``.
 146   -  ``-fsanitize=integer``: Checks for undefined or suspicious integer
 147      behavior (e.g. unsigned integer overflow).
 148   -  ``-fsanitize=nullability``: Enables ``nullability-arg``,
 149      ``nullability-assign``, and ``nullability-return``. While violating
 150      nullability does not have undefined behavior, it is often unintentional,
 151      so UBSan offers to catch it.
 152
 153 Volatile
 154 --------
 155
 156 The ``null``, ``alignment``, ``object-size``, and ``vptr`` checks do not apply
 157 to pointers to types with the ``volatile`` qualifier.
 158
 159 Minimal Runtime
 160 ===============
 161
 162 There is a minimal UBSan runtime available suitable for use in production
 163 environments. This runtime has a small attack surface. It only provides very
 164 basic issue logging and deduplication, and does not support ``-fsanitize=vptr``
 165 checking.
 166
 167 To use the minimal runtime, add ``-fsanitize-minimal-runtime`` to the clang
 168 command line options. For example, if you're used to compiling with
 169 ``-fsanitize=undefined``, you could enable the minimal runtime with
 170 ``-fsanitize=undefined -fsanitize-minimal-runtime``.
 171
 172 Stack traces and report symbolization
 173 =====================================
 174 If you want UBSan to print symbolized stack trace for each error report, you
 175 will need to:
 176
 177 #. Compile with ``-g`` and ``-fno-omit-frame-pointer`` to get proper debug
 178    information in your binary.
 179 #. Run your program with environment variable
 180    ``UBSAN_OPTIONS=print_stacktrace=1``.
 181 #. Make sure ``llvm-symbolizer`` binary is in ``PATH``.
 182
 183 Silencing Unsigned Integer Overflow
 184 ===================================
 185 To silence reports from unsigned integer overflow, you can set
 186 ``UBSAN_OPTIONS=silence_unsigned_overflow=1``.  This feature, combined with
 187 ``-fsanitize-recover=unsigned-integer-overflow``, is particularly useful for
 188 providing fuzzing signal without blowing up logs.
 189
 190 Issue Suppression
 191 =================
 192
 193 UndefinedBehaviorSanitizer is not expected to produce false positives.
 194 If you see one, look again; most likely it is a true positive!
 195
 196 Disabling Instrumentation with ``__attribute__((no_sanitize("undefined")))``
 197 ----------------------------------------------------------------------------
 198
 199 You disable UBSan checks for particular functions with
 200 ``__attribute__((no_sanitize("undefined")))``. You can use all values of
 201 ``-fsanitize=`` flag in this attribute, e.g. if your function deliberately
 202 contains possible signed integer overflow, you can use
 203 ``__attribute__((no_sanitize("signed-integer-overflow")))``.
 204
 205 This attribute may not be
 206 supported by other compilers, so consider using it together with
 207 ``#if defined(__clang__)``.
 208
 209 Suppressing Errors in Recompiled Code (Blacklist)
 210 -------------------------------------------------
 211
 212 UndefinedBehaviorSanitizer supports ``src`` and ``fun`` entity types in
 213 :doc:`SanitizerSpecialCaseList`, that can be used to suppress error reports
 214 in the specified source files or functions.
 215
 216 Runtime suppressions
 217 --------------------
 218
 219 Sometimes you can suppress UBSan error reports for specific files, functions,
 220 or libraries without recompiling the code. You need to pass a path to
 221 suppression file in a ``UBSAN_OPTIONS`` environment variable.
 222
 223 .. code-block:: bash
 224
 225     UBSAN_OPTIONS=suppressions=MyUBSan.supp
 226
 227 You need to specify a :ref:`check <ubsan-checks>` you are suppressing and the
 228 bug location. For example:
 229
 230 .. code-block:: bash
 231
 232   signed-integer-overflow:file-with-known-overflow.cpp
 233   alignment:function_doing_unaligned_access
 234   vptr:shared_object_with_vptr_failures.so
 235
 236 There are several limitations:
 237
 238 * Sometimes your binary must have enough debug info and/or symbol table, so
 239   that the runtime could figure out source file or function name to match
 240   against the suppression.
 241 * It is only possible to suppress recoverable checks. For the example above,
 242   you can additionally pass
 243   ``-fsanitize-recover=signed-integer-overflow,alignment,vptr``, although
 244   most of UBSan checks are recoverable by default.
 245 * Check groups (like ``undefined``) can't be used in suppressions file, only
 246   fine-grained checks are supported.
 247
 248 Supported Platforms
 249 ===================
 250
 251 UndefinedBehaviorSanitizer is supported on the following OS:
 252
 253 * Android
 254 * Linux
 255 * NetBSD
 256 * FreeBSD
 257 * OpenBSD
 258 * OS X 10.6 onwards
 259
 260 Current Status
 261 ==============
 262
 263 UndefinedBehaviorSanitizer is available on selected platforms starting from LLVM
 264 3.3. The test suite is integrated into the CMake build and can be run with
 265 ``check-ubsan`` command.
 266
 267 Additional Configuration
 268 ========================
 269
 270 UndefinedBehaviorSanitizer adds static check data for each check unless it is
 271 in trap mode. This check data includes the full file name. The option
 272 ``-fsanitize-undefined-strip-path-components=N`` can be used to trim this
 273 information. If ``N`` is positive, file information emitted by
 274 UndefinedBehaviorSanitizer will drop the first ``N`` components from the file
 275 path. If ``N`` is negative, the last ``N`` components will be kept.
 276
 277 Example
 278 -------
 279
 280 For a file called ``/code/library/file.cpp``, here is what would be emitted:
 281 * Default (No flag, or ``-fsanitize-undefined-strip-path-components=0``): ``/code/library/file.cpp``
 282 * ``-fsanitize-undefined-strip-path-components=1``: ``code/library/file.cpp``
 283 * ``-fsanitize-undefined-strip-path-components=2``: ``library/file.cpp``
 284 * ``-fsanitize-undefined-strip-path-components=-1``: ``file.cpp``
 285 * ``-fsanitize-undefined-strip-path-components=-2``: ``library/file.cpp``
 286
 287 More Information
 288 ================
 289
 290 * From LLVM project blog:
 291   `What Every C Programmer Should Know About Undefined Behavior
 292   <http://blog.llvm.org/2011/05/what-every-c-programmer-should-know.html>`_
 293 * From John Regehr's *Embedded in Academia* blog:
 294   `A Guide to Undefined Behavior in C and C++
 295   <http://blog.regehr.org/archives/213>`_