diff --git a/clang/docs/ReleaseNotes.rst b/clang/docs/ReleaseNotes.rst index 0eee71d00a2c5..0f036e90e06c5 100644 --- a/clang/docs/ReleaseNotes.rst +++ b/clang/docs/ReleaseNotes.rst @@ -540,6 +540,14 @@ Sanitizers This new flag should allow those projects to enable integer sanitizers with less noise. +- Arithmetic overflow sanitizers ``-fsanitize=signed-integer-overflow`` and + ``-fsanitize=unsigned-integer-overflow`` as well as the implicit integer + truncation sanitizers ``-fsanitize=implicit-signed-integer-truncation`` and + ``-fsanitize=implicit-unsigned-integer-truncation`` now properly support the + "type" prefix within `Sanitizer Special Case Lists (SSCL) + `_. See that link + for examples. + Python Binding Changes ---------------------- - Fixed an issue that led to crashes when calling ``Type.get_exception_specification_kind``. diff --git a/clang/docs/SanitizerSpecialCaseList.rst b/clang/docs/SanitizerSpecialCaseList.rst index c7fb0fa3f8a82..13f71b878d4cc 100644 --- a/clang/docs/SanitizerSpecialCaseList.rst +++ b/clang/docs/SanitizerSpecialCaseList.rst @@ -15,8 +15,9 @@ file at compile-time. Goal and usage ============== -Users of sanitizer tools, such as :doc:`AddressSanitizer`, :doc:`ThreadSanitizer` -or :doc:`MemorySanitizer` may want to disable or alter some checks for +Users of sanitizer tools, such as :doc:`AddressSanitizer`, +:doc:`ThreadSanitizer`, :doc:`MemorySanitizer` or :doc: +`UndefinedBehaviorSanitizer` may want to disable or alter some checks for certain source-level entities to: * speedup hot function, which is known to be correct; @@ -48,6 +49,63 @@ Example $ clang -fsanitize=address -fsanitize-ignorelist=ignorelist.txt foo.c ; ./a.out # No error report here. +Usage with UndefinedBehaviorSanitizer +===================================== + +The arithmetic overflow sanitizers ``unsigned-integer-overflow`` and +``signed-integer-overflow`` as well as the implicit integer truncation +sanitizers ``implicit-signed-integer-truncation`` and +``implicit-unsigned-integer-truncation`` support the ability to adjust +instrumentation based on type. + +.. code-block:: bash + + $ cat foo.c + void foo() { + int a = 2147483647; // INT_MAX + ++a; // Normally, an overflow with -fsanitize=signed-integer-overflow + } + $ cat ignorelist.txt + [signed-integer-overflow] + type:int + $ clang -fsanitize=signed-integer-overflow -fsanitize-ignorelist=ignorelist.txt foo.c ; ./a.out + # no signed-integer-overflow error + +Supplying ``ignorelist.txt`` with ``-fsanitize-ignorelist=ignorelist.txt`` +disables overflow sanitizer instrumentation for arithmetic operations +containing values of type ``int``, for example. Custom types may be used. + +The following SCL categories are supported: ``=allow``, ``=skip`` and +``=forbid``. The ``allow`` category is the default for any entry and specifies +that the query, if matched, will have its sanitizer instrumentation ignored. +Conversely, both ``skip`` and ``forbid`` cause their queries, if matched, to be +left out of the ignorelist -- essentially ensuring sanitizer instrumentation +remains for those types. This is useful for whitelisting specific types. + +With this, one may disable instrumentation for all types and specifically allow +instrumentation for one or many types. + +.. code-block:: bash + + $ cat ignorelist.txt + [implicit-signed-integer-truncation] + type:*=allow + type:T=skip + $ cat foo.c + typedef char T; + typedef char U; + void foo(int toobig) { + T a = toobig; // instrumented + U b = toobig; // not instrumented + char c = toobig; // also not instrumented + } + +Note that ``skip`` and ``forbid`` operate exactly the same in this context and +both options exist simply for conformity with the `-fprofile-list +`_ +syntax for adjusting profile instrumentation. You do not need to specify any +`default:` for ``-fsanitize-ignorelist`` SSCLs, though. + Format ======