[PATCH] D152650: [docs] Improve UndefinedBehaviorSanitizer.rst

[Fangrui Song via Phabricator via cfe-commits]

This revision was landed with ongoing or failed builds.
This revision was automatically updated to reflect the committed changes.
Closed by commit rGee0367ef13f8: [docs] Improve UndefinedBehaviorSanitizer.rst (authored by MaskRay).

Changed prior to commit:
  https://reviews.llvm.org/D152650?vs=530645&id=530647#toc

Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D152650/new/

https://reviews.llvm.org/D152650

Files:
  clang/docs/UndefinedBehaviorSanitizer.rst


Index: clang/docs/UndefinedBehaviorSanitizer.rst
===================================================================
--- clang/docs/UndefinedBehaviorSanitizer.rst
+++ clang/docs/UndefinedBehaviorSanitizer.rst
@@ -32,10 +32,11 @@
 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 @@
   % ./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


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D152650.530647.patch
Type: text/x-patch
Size: 4038 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/cfe-commits/attachments/20230612/987202b4/attachment.bin>