213 lines · plain
1===========================2Sanitizer special case list3===========================4 5.. contents::6 :local:7 8Introduction9============10 11This document describes the way to disable or alter the behavior of12sanitizer tools for certain source-level entities by providing a special13file at compile-time.14 15Goal and usage16==============17 18Users of sanitizer tools, such as :doc:`AddressSanitizer`,19:doc:`HardwareAssistedAddressSanitizerDesign`, :doc:`ThreadSanitizer`,20:doc:`MemorySanitizer` or :doc:`UndefinedBehaviorSanitizer` may want to disable21or alter some checks for certain source-level entities to:22 23* speedup hot function, which is known to be correct;24* ignore a function that does some low-level magic (e.g. walks through the25 thread stack, bypassing the frame boundaries);26* ignore a known problem.27 28To achieve this, user may create a file listing the entities they want to29ignore, and pass it to clang at compile-time using30``-fsanitize-ignorelist`` flag. See :doc:`UsersManual` for details.31 32Example33=======34 35.. code-block:: bash36 37 $ cat foo.c38 #include <stdlib.h>39 void bad_foo() {40 int *a = (int*)malloc(40);41 a[10] = 1;42 free(a);43 }44 int main() { bad_foo(); }45 $ cat ignorelist.txt46 # Ignore reports from bad_foo function.47 fun:bad_foo48 $ clang -fsanitize=address foo.c ; ./a.out49 # AddressSanitizer prints an error report.50 $ clang -fsanitize=address -fsanitize-ignorelist=ignorelist.txt foo.c ; ./a.out51 # No error report here.52 53Usage with UndefinedBehaviorSanitizer54=====================================55 56``unsigned-integer-overflow``, ``signed-integer-overflow``,57``implicit-signed-integer-truncation``,58``implicit-unsigned-integer-truncation``, and ``enum`` sanitizers support the59ability to adjust instrumentation based on type.60 61By default, supported sanitizers will have their instrumentation disabled for62entries specified within an ignorelist.63 64.. code-block:: bash65 66 $ cat foo.c67 void foo() {68 int a = 2147483647; // INT_MAX69 ++a; // Normally, an overflow with -fsanitize=signed-integer-overflow70 }71 $ cat ignorelist.txt72 [signed-integer-overflow]73 type:int74 $ clang -fsanitize=signed-integer-overflow -fsanitize-ignorelist=ignorelist.txt foo.c ; ./a.out75 # no signed-integer-overflow error76 77For example, supplying the above ``ignorelist.txt`` to78``-fsanitize-ignorelist=ignorelist.txt`` disables overflow sanitizer79instrumentation for arithmetic operations containing values of type ``int``.80 81The ``=sanitize`` category is also supported. Any ``=sanitize`` category82entries enable sanitizer instrumentation, even if it was ignored by entries83before. Entries can be ``src``, ``type``, ``global``, ``fun``, and84``mainfile``.85 86With this, one may disable instrumentation for some or all types and87specifically allow instrumentation for one or many types -- including types88created via ``typedef``. This is a way to achieve a sort of "allowlist" for89supported sanitizers.90 91.. code-block:: bash92 93 $ cat ignorelist.txt94 [implicit-signed-integer-truncation]95 type:*96 type:T=sanitize97 98 $ cat foo.c99 typedef char T;100 typedef char U;101 void foo(int toobig) {102 T a = toobig; // instrumented103 U b = toobig; // not instrumented104 char c = toobig; // also not instrumented105 }106 107If multiple entries match the source, then the latest entry takes the108precedence. Here are a few examples.109 110.. code-block:: bash111 112 $ cat ignorelist1.txt113 # test.cc will not be instrumented.114 src:*115 src:*/mylib/*=sanitize116 src:*/mylib/test.cc117 118 $ cat ignorelist2.txt119 # test.cc will be instrumented.120 src:*121 src:*/mylib/test.cc122 src:*/mylib/*=sanitize123 124 $ cat ignorelist3.txt125 # Type T will not be instrumented.126 type:*127 type:T=sanitize128 type:T129 130 $ cat ignorelist4.txt131 # Function `bad_bar` will be instrumented.132 # Function `good_bar` will not be instrumented.133 fun:*134 fun:*bar135 fun:bad_bar=sanitize136 137Format138======139 140Ignorelists consist of entries, optionally grouped into sections. Empty lines141and lines starting with "#" are ignored.142 143.. note::144 145 Prior to Clang 18, section names and entries described below use a variant of146 regex where ``*`` is translated to ``.*``. Clang 18 (`D154014147 <https://reviews.llvm.org/D154014>`) switches to glob and plans to remove148 regex support in Clang 19.149 150 For Clang 18, regex is supported if ``#!special-case-list-v1`` is the first151 line of the file.152 153 Many special case lists use ``.`` to indicate the literal character and do154 not use regex metacharacters such as ``(``, ``)``. They are unaffected by the155 regex to glob transition. For more details, see `this discourse post156 <https://discourse.llvm.org/t/use-glob-instead-of-regex-for-specialcaselists/71666>`_.157 158Section names are globs written in square brackets that denote159which sanitizer the following entries apply to. For example, ``[address]``160specifies AddressSanitizer while ``[{cfi-vcall,cfi-icall}]`` specifies Control161Flow Integrity virtual and indirect call checking. Entries without a section162will be placed under the ``[*]`` section applying to all enabled sanitizers.163 164Entries contain an entity type, followed by a colon and a glob,165specifying the names of the entities, optionally followed by an equals sign and166a tool-specific category, e.g. ``fun:*ExampleFunc=example_category``.167Two generic entity types are ``src`` and168``fun``, which allow users to specify source files and functions, respectively.169Some sanitizer tools may introduce custom entity types and categories - refer to170tool-specific docs.171 172.. code-block:: bash173 174 # Lines starting with # are ignored.175 # Turn off checks for the source file176 # Entries without sections are placed into [*] and apply to all sanitizers177 src:path/to/source/file.c178 src:*/source/file.c179 # Turn off checks for this main file, including files included by it.180 # Useful when the main file instead of an included file should be ignored.181 mainfile:file.c182 # Turn off checks for a particular functions (use mangled names):183 fun:_Z8MyFooBarv184 # Glob brace expansions and character ranges are supported185 fun:bad_{foo,bar}186 src:bad_source[1-9].c187 # "*" matches zero or more characters188 src:bad/sources/*189 fun:*BadFunction*190 # Specific sanitizer tools may introduce categories.191 src:/special/path/*=special_sources192 # Sections can be used to limit ignorelist entries to specific sanitizers193 [address]194 fun:*BadASanFunc*195 # Section names are globs196 [{cfi-vcall,cfi-icall}]197 fun:*BadCfiCall198 199``mainfile`` is similar to applying ``-fno-sanitize=`` to a set of files but200does not need plumbing into the build system. This works well for internal201linkage functions but has a caveat for C++ vague linkage functions.202 203C++ vague linkage functions (e.g. inline functions, template instantiations) are204deduplicated at link time. A function (in an included file) ignored by a205specific ``mainfile`` pattern may not be the prevailing copy picked by the206linker. Therefore, using ``mainfile`` requires caution. It may still be useful,207e.g. when patterns are picked in a way to ensure the prevailing one is ignored.208(There is action-at-a-distance risk.)209 210``mainfile`` can be useful enabling a ubsan check for a large code base when211finding the direct stack frame triggering the failure for every failure is212difficult.213