[UBSan] Add documentation for runtime issue suppression.

git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@259260 91177308-0d34-0410-b5e6-96231b3b80d8

diff --git a/docs/UndefinedBehaviorSanitizer.rst b/docs/UndefinedBehaviorSanitizer.rst
index 37ff16d9a9e9b5925af5ff3709fcf52cd8e2e54c..2a133501dd952fb3ca2a9f169c7311f4214768e5 100644 (file)
--- a/docs/UndefinedBehaviorSanitizer.rst
+++ b/docs/UndefinedBehaviorSanitizer.rst
@@ -168,6 +168,38 @@ UndefinedBehaviorSanitizer supports ``src`` and ``fun`` entity types in
 :doc:`SanitizerSpecialCaseList`, that can be used to suppress error reports
 in the specified source files or functions.
 
+Runtime suppressions
+--------------------
+
+Sometimes you can suppress UBSan error reports for specific files, functions,
+or libraries without recompiling the code. You need to pass a path to
+suppression file in a ``UBSAN_OPTIONS`` environment variable.
+
+.. code-block:: bash
+
+    UBSAN_OPTIONS=suppressions=MyUBSan.supp
+
+You need to specify a :ref:`check <ubsan-checks>` you are suppressing and the
+bug location. For example:
+
+.. code-block:: bash
+
+  signed-integer-overflow:file-with-known-overflow.cpp
+  alignment:function_doing_unaligned_access
+  vptr:shared_object_with_vptr_failures.so
+
+There are several limitations:
+
+* Sometimes your binary must have enough debug info and/or symbol table, so
+  that the runtime could figure out source file or function name to match
+  against the suppression.
+* It is only possible to suppress recoverable checks. For the example above,
+  you can additionally pass
+  ``-fsanitize-recover=signed-integer-overflow,alignment,vptr``, although
+  most of UBSan checks are recoverable by default.
+* Check groups (like ``undefined``) can't be used in suppressions file, only
+  fine-grained checks are supported.
+
 Supported Platforms
 ===================