diff --git a/clang/docs/UndefinedBehaviorSanitizer.rst b/clang/docs/UndefinedBehaviorSanitizer.rst --- a/clang/docs/UndefinedBehaviorSanitizer.rst +++ b/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 the trap mode. You can use ``clang`` instead of ``clang++`` if you're +compiling/linking C code. .. code-block:: console @@ -49,28 +50,50 @@ % ./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 ` 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. + +.. code-block:: console + + # Enable all checks in the "undefined" group, but disable "alignment". + % clang -fsanitize=undefined -fno-sanitize=alignment a.c + + # Enable only "alignment". + # -fno-sanitize=undefined nullifies the previous -fsanitize=undefined. + % clang -fsanitize=undefined -fno-sanitize=undefined -fsanitize=alignment a.c + +For most checks (:ref:`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: -* ``-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. -Note that the ``trap`` / ``recover`` options do not enable the corresponding -sanitizer, and in general need to be accompanied by a suitable ``-fsanitize=`` -flag. - -For example if you compile/link your program as: +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