[clang] ee0367e - [docs] Improve UndefinedBehaviorSanitizer.rst

[Fangrui Song via cfe-commits]

Author: Fangrui Song
Date: 2023-06-12T13:04:29-07:00
New Revision: ee0367ef13f87cdac869647d731f820a98746fe6

URL: https://github.com/llvm/llvm-project/commit/ee0367ef13f87cdac869647d731f820a98746fe6
DIFF: https://github.com/llvm/llvm-project/commit/ee0367ef13f87cdac869647d731f820a98746fe6.diff

LOG: [docs] Improve UndefinedBehaviorSanitizer.rst

* Mention that -fsanitize= and -fno-sanitize= apply to check groups.
* Mention "all" can be used as a check group.
* Mention that -fsanitize-trap= and -fsanitize-recover= lead to no unused command line option warning.
* Mention that trap mode typically causes the program to terminate due to a `SIGILL` or `SIGTRAP` signal.

Reviewed By: #sanitizers, vitalybuka

Differential Revision: https://reviews.llvm.org/D152650

Added: 
    

Modified: 
    clang/docs/UndefinedBehaviorSanitizer.rst

Removed: 
    


################################################################################
diff  --git a/clang/docs/UndefinedBehaviorSanitizer.rst b/clang/docs/UndefinedBehaviorSanitizer.rst
index bfcdeba0632e5..d8bad280ba45a 100644
--- a/clang/docs/UndefinedBehaviorSanitizer.rst
+++ b/clang/docs/UndefinedBehaviorSanitizer.rst
@@ -32,10 +32,11 @@ Build LLVM/Clang with `CMake <https://llvm.org/docs/CMake.html>`_.
 Usage
 =====
 
-Use ``clang++`` to compile and link your program with ``-fsanitize=undefined``
-flag. Make sure to use ``clang++`` (not ``ld``) as a linker, so that your
-executable is linked with proper UBSan runtime libraries. You can use ``clang``
-instead of ``clang++`` if you're compiling/linking C code.
+Use ``clang++`` to compile and link your program with the ``-fsanitize=undefined``
+option. Make sure to use ``clang++`` (not ``ld``) as a linker, so that your
+executable is linked with proper UBSan runtime libraries, unless all enabled
+checks use trap mode. You can use ``clang`` instead of ``clang++`` if you're
+compiling/linking C code.
 
 .. code-block:: console
 
@@ -49,28 +50,56 @@ instead of ``clang++`` if you're compiling/linking C code.
   % ./a.out
   test.cc:3:5: runtime error: signed integer overflow: 2147483647 + 1 cannot be represented in type 'int'
 
-You can enable only a subset of :ref:`checks <ubsan-checks>` offered by UBSan,
-and define the desired behavior for each kind of check:
+You can use ``-fsanitize=...`` and ``-fno-sanitize=`` to enable and disable one
+check or one check group. For an individual check, the last option that enabling
+or disabling it wins.
 
-* ``-fsanitize=...``: print a verbose error report and continue execution (default);
-* ``-fno-sanitize-recover=...``: print a verbose error report and exit the program;
-* ``-fsanitize-trap=...``: execute a trap instruction (doesn't require UBSan run-time support).
-* ``-fno-sanitize=...``: disable any check, e.g., -fno-sanitize=alignment.
+.. code-block:: console
+
+  # Enable all checks in the "undefined" group, but disable "alignment".
+  % clang -fsanitize=undefined -fno-sanitize=alignment a.c
+
+  # Enable just "alignment".
+  % clang -fsanitize=alignment a.c
 
-Note that the ``trap`` / ``recover`` options do not enable the corresponding
-sanitizer, and in general need to be accompanied by a suitable ``-fsanitize=``
-flag.
+  # The same. -fno-sanitize=undefined nullifies the previous -fsanitize=undefined.
+  % clang -fsanitize=undefined -fno-sanitize=undefined -fsanitize=alignment a.c
 
-For example if you compile/link your program as:
+For most checks (:ref:`checks <ubsan-checks>`), the instrumented program prints
+a verbose error report and continues execution upon a failed check.
+You can use the following options to change the error reporting behavior:
+
+* ``-fno-sanitize-recover=...``: print a verbose error report and exit the program;
+* ``-fsanitize-trap=...``: execute a trap instruction (doesn't require UBSan
+  run-time support). If the signal is not caught, the program will typically
+  terminate due to a ``SIGILL`` or ``SIGTRAP`` signal.
+
+For example:
 
 .. code-block:: console
 
-  % clang++ -fsanitize=signed-integer-overflow,null,alignment -fno-sanitize-recover=null -fsanitize-trap=alignment
+  % clang++ -fsanitize=signed-integer-overflow,null,alignment -fno-sanitize-recover=null -fsanitize-trap=alignment a.cc
 
-the program will continue execution after signed integer overflows, exit after
+The program will continue execution after signed integer overflows, exit after
 the first invalid use of a null pointer, and trap after the first use of misaligned
 pointer.
 
+.. code-block:: console
+
+  % clang++ -fsanitize=undefined -fsanitize-trap=all a.cc
+
+All checks in the "undefined" group are put into trap mode. Since no check
+needs run-time support, the UBSan run-time library it not linked. Note that
+some other sanitizers also support trap mode and ``-fsanitize-trap=all``
+enables trap mode for them.
+
+.. code-block:: console
+
+  % clang -fsanitize-trap=undefined -fsanitize-recover=all a.c
+
+``-fsanitize-trap=`` and ``-fsanitize-recover=`` are a no-op in the absence of
+a ``-fsanitize=`` option. There is no unused command line option warning.
+
 .. _ubsan-checks:
 
 Available checks