MaskRay updated this revision to Diff 530645. MaskRay marked an inline comment as done. MaskRay edited the summary of this revision. MaskRay added a comment.
better -fsanitize=... -fno-sanitize example Add "If the signal is not caught, the program will typically terminate due to a ``SIGILL`` or ``SIGTRAP`` signal." 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. + +.. code-block:: console + + # Enable all checks in the "undefined" group, but disable "alignment". + % clang -fsanitize=undefined -fno-sanitize=alignment a.c + + # Enable only "alignment". + % clang -fsanitize=alignment a.c + + # The same. -fno-sanitize=undefined nullifies the previous -fsanitize=undefined. + % clang -fsanitize=undefined -fno-sanitize=undefined -fsanitize=alignment a.c + +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: -* ``-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. +* ``-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. -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
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. + +.. code-block:: console + + # Enable all checks in the "undefined" group, but disable "alignment". + % clang -fsanitize=undefined -fno-sanitize=alignment a.c + + # Enable only "alignment". + % clang -fsanitize=alignment a.c + + # The same. -fno-sanitize=undefined nullifies the previous -fsanitize=undefined. + % clang -fsanitize=undefined -fno-sanitize=undefined -fsanitize=alignment a.c + +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: -* ``-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. +* ``-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. -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
_______________________________________________ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
