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 <http://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
57For 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
63the program will continue execution after signed integer overflows, exit after
64the first invalid use of a null pointer, and trap after the first use of misaligned
65pointer.
66
67.. _ubsan-checks:
68
69Available checks
70================
71
72Available 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
141You 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
153Volatile
154--------
155
156The ``null``, ``alignment``, ``object-size``, and ``vptr`` checks do not apply
157to pointers to types with the ``volatile`` qualifier.
158
159Minimal Runtime
160===============
161
162There is a minimal UBSan runtime available suitable for use in production
163environments. This runtime has a small attack surface. It only provides very
164basic issue logging and deduplication, and does not support ``-fsanitize=vptr``
165checking.
166
167To use the minimal runtime, add ``-fsanitize-minimal-runtime`` to the clang
168command 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
172Stack traces and report symbolization
173=====================================
174If you want UBSan to print symbolized stack trace for each error report, you
175will 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
183Issue Suppression
184=================
185
186UndefinedBehaviorSanitizer is not expected to produce false positives.
187If you see one, look again; most likely it is a true positive!
188
189Disabling Instrumentation with ``__attribute__((no_sanitize("undefined")))``
190----------------------------------------------------------------------------
191
192You disable UBSan checks for particular functions with
193``__attribute__((no_sanitize("undefined")))``. You can use all values of
194``-fsanitize=`` flag in this attribute, e.g. if your function deliberately
195contains possible signed integer overflow, you can use
196``__attribute__((no_sanitize("signed-integer-overflow")))``.
197
198This attribute may not be
199supported by other compilers, so consider using it together with
200``#if defined(__clang__)``.
201
202Suppressing Errors in Recompiled Code (Blacklist)
203-------------------------------------------------
204
205UndefinedBehaviorSanitizer supports ``src`` and ``fun`` entity types in
206:doc:`SanitizerSpecialCaseList`, that can be used to suppress error reports
207in the specified source files or functions.
208
209Runtime suppressions
210--------------------
211
212Sometimes you can suppress UBSan error reports for specific files, functions,
213or libraries without recompiling the code. You need to pass a path to
214suppression file in a ``UBSAN_OPTIONS`` environment variable.
215
216.. code-block:: bash
217
218    UBSAN_OPTIONS=suppressions=MyUBSan.supp
219
220You need to specify a :ref:`check <ubsan-checks>` you are suppressing and the
221bug location. For example:
222
223.. code-block:: bash
224
225  signed-integer-overflow:file-with-known-overflow.cpp
226  alignment:function_doing_unaligned_access
227  vptr:shared_object_with_vptr_failures.so
228
229There are several limitations:
230
231* Sometimes your binary must have enough debug info and/or symbol table, so
232  that the runtime could figure out source file or function name to match
233  against the suppression.
234* It is only possible to suppress recoverable checks. For the example above,
235  you can additionally pass
236  ``-fsanitize-recover=signed-integer-overflow,alignment,vptr``, although
237  most of UBSan checks are recoverable by default.
238* Check groups (like ``undefined``) can't be used in suppressions file, only
239  fine-grained checks are supported.
240
241Supported Platforms
242===================
243
244UndefinedBehaviorSanitizer is supported on the following OS:
245
246* Android
247* Linux
248* FreeBSD
249* OS X 10.6 onwards
250
251and for the following architectures:
252
253* i386/x86\_64
254* ARM
255* AArch64
256* PowerPC64
257* MIPS/MIPS64
258
259Current Status
260==============
261
262UndefinedBehaviorSanitizer is available on selected platforms starting from LLVM
2633.3. The test suite is integrated into the CMake build and can be run with
264``check-ubsan`` command.
265
266Additional Configuration
267========================
268
269UndefinedBehaviorSanitizer adds static check data for each check unless it is
270in trap mode. This check data includes the full file name. The option
271``-fsanitize-undefined-strip-path-components=N`` can be used to trim this
272information. If ``N`` is positive, file information emitted by
273UndefinedBehaviorSanitizer will drop the first ``N`` components from the file
274path. If ``N`` is negative, the last ``N`` components will be kept.
275
276Example
277-------
278
279For a file called ``/code/library/file.cpp``, here is what would be emitted:
280* Default (No flag, or ``-fsanitize-undefined-strip-path-components=0``): ``/code/library/file.cpp``
281* ``-fsanitize-undefined-strip-path-components=1``: ``code/library/file.cpp``
282* ``-fsanitize-undefined-strip-path-components=2``: ``library/file.cpp``
283* ``-fsanitize-undefined-strip-path-components=-1``: ``file.cpp``
284* ``-fsanitize-undefined-strip-path-components=-2``: ``library/file.cpp``
285
286More Information
287================
288
289* From LLVM project blog:
290  `What Every C Programmer Should Know About Undefined Behavior
291  <http://blog.llvm.org/2011/05/what-every-c-programmer-should-know.html>`_
292* From John Regehr's *Embedded in Academia* blog:
293  `A Guide to Undefined Behavior in C and C++
294  <http://blog.regehr.org/archives/213>`_
295