1=========================== 2Sanitizer special case list 3=========================== 4 5.. contents:: 6 :local: 7 8Introduction 9============ 10 11This document describes the way to disable or alter the behavior of 12sanitizer tools for certain source-level entities by providing a special 13file at compile-time. 14 15Goal and usage 16============== 17 18Users of sanitizer tools, such as :doc:`AddressSanitizer`, 19:doc:`HardwareAssistedAddressSanitizerDesign`, :doc:`ThreadSanitizer`, 20:doc:`MemorySanitizer` or :doc:`UndefinedBehaviorSanitizer` may want to disable 21or 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 the 25 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 to 29ignore, and pass it to clang at compile-time using 30``-fsanitize-ignorelist`` flag. See :doc:`UsersManual` for details. 31 32Example 33======= 34 35.. code-block:: bash 36 37 $ cat foo.c 38 #include <stdlib.h> 39 void bad_foo() { 40 int *a = (int*)malloc(40); 41 a[10] = 1; 42 } 43 int main() { bad_foo(); } 44 $ cat ignorelist.txt 45 # Ignore reports from bad_foo function. 46 fun:bad_foo 47 $ clang -fsanitize=address foo.c ; ./a.out 48 # AddressSanitizer prints an error report. 49 $ clang -fsanitize=address -fsanitize-ignorelist=ignorelist.txt foo.c ; ./a.out 50 # No error report here. 51 52Usage with UndefinedBehaviorSanitizer 53===================================== 54 55``unsigned-integer-overflow``, ``signed-integer-overflow``, 56``implicit-signed-integer-truncation``, 57``implicit-unsigned-integer-truncation``, and ``enum`` sanitizers support the 58ability to adjust instrumentation based on type. 59 60By default, supported sanitizers will have their instrumentation disabled for 61types specified within an ignorelist. 62 63.. code-block:: bash 64 65 $ cat foo.c 66 void foo() { 67 int a = 2147483647; // INT_MAX 68 ++a; // Normally, an overflow with -fsanitize=signed-integer-overflow 69 } 70 $ cat ignorelist.txt 71 [signed-integer-overflow] 72 type:int 73 $ clang -fsanitize=signed-integer-overflow -fsanitize-ignorelist=ignorelist.txt foo.c ; ./a.out 74 # no signed-integer-overflow error 75 76For example, supplying the above ``ignorelist.txt`` to 77``-fsanitize-ignorelist=ignorelist.txt`` disables overflow sanitizer 78instrumentation for arithmetic operations containing values of type ``int``. 79 80The ``=sanitize`` category is also supported. Any types assigned to the 81``sanitize`` category will have their sanitizer instrumentation remain. If the 82same type appears within or across ignorelists with different categories the 83``sanitize`` category takes precedence -- regardless of order. 84 85With this, one may disable instrumentation for some or all types and 86specifically allow instrumentation for one or many types -- including types 87created via ``typedef``. This is a way to achieve a sort of "allowlist" for 88supported sanitizers. 89 90.. code-block:: bash 91 92 $ cat ignorelist.txt 93 [implicit-signed-integer-truncation] 94 type:* 95 type:T=sanitize 96 97 $ cat foo.c 98 typedef char T; 99 typedef char U; 100 void foo(int toobig) { 101 T a = toobig; // instrumented 102 U b = toobig; // not instrumented 103 char c = toobig; // also not instrumented 104 } 105 106Format 107====== 108 109Ignorelists consist of entries, optionally grouped into sections. Empty lines 110and lines starting with "#" are ignored. 111 112.. note:: 113 114 Prior to Clang 18, section names and entries described below use a variant of 115 regex where ``*`` is translated to ``.*``. Clang 18 (`D154014 116 <https://reviews.llvm.org/D154014>`) switches to glob and plans to remove 117 regex support in Clang 19. 118 119 For Clang 18, regex is supported if ``#!special-case-list-v1`` is the first 120 line of the file. 121 122 Many special case lists use ``.`` to indicate the literal character and do 123 not use regex metacharacters such as ``(``, ``)``. They are unaffected by the 124 regex to glob transition. For more details, see `this discourse post 125 <https://discourse.llvm.org/t/use-glob-instead-of-regex-for-specialcaselists/71666>`_. 126 127Section names are globs written in square brackets that denote 128which sanitizer the following entries apply to. For example, ``[address]`` 129specifies AddressSanitizer while ``[{cfi-vcall,cfi-icall}]`` specifies Control 130Flow Integrity virtual and indirect call checking. Entries without a section 131will be placed under the ``[*]`` section applying to all enabled sanitizers. 132 133Entries contain an entity type, followed by a colon and a glob, 134specifying the names of the entities, optionally followed by an equals sign and 135a tool-specific category, e.g. ``fun:*ExampleFunc=example_category``. 136Two generic entity types are ``src`` and 137``fun``, which allow users to specify source files and functions, respectively. 138Some sanitizer tools may introduce custom entity types and categories - refer to 139tool-specific docs. 140 141.. code-block:: bash 142 143 # The line above is explained in the note above 144 # Lines starting with # are ignored. 145 # Turn off checks for the source file 146 # Entries without sections are placed into [*] and apply to all sanitizers 147 src:path/to/source/file.c 148 src:*/source/file.c 149 # Turn off checks for this main file, including files included by it. 150 # Useful when the main file instead of an included file should be ignored. 151 mainfile:file.c 152 # Turn off checks for a particular functions (use mangled names): 153 fun:_Z8MyFooBarv 154 # Glob brace expansions and character ranges are supported 155 fun:bad_{foo,bar} 156 src:bad_source[1-9].c 157 # "*" matches zero or more characters 158 src:bad/sources/* 159 fun:*BadFunction* 160 # Specific sanitizer tools may introduce categories. 161 src:/special/path/*=special_sources 162 # Sections can be used to limit ignorelist entries to specific sanitizers 163 [address] 164 fun:*BadASanFunc* 165 # Section names are globs 166 [{cfi-vcall,cfi-icall}] 167 fun:*BadCfiCall 168 169``mainfile`` is similar to applying ``-fno-sanitize=`` to a set of files but 170does not need plumbing into the build system. This works well for internal 171linkage functions but has a caveat for C++ vague linkage functions. 172 173C++ vague linkage functions (e.g. inline functions, template instantiations) are 174deduplicated at link time. A function (in an included file) ignored by a 175specific ``mainfile`` pattern may not be the prevailing copy picked by the 176linker. Therefore, using ``mainfile`` requires caution. It may still be useful, 177e.g. when patterns are picked in a way to ensure the prevailing one is ignored. 178(There is action-at-a-distance risk.) 179 180``mainfile`` can be useful enabling a ubsan check for a large code base when 181finding the direct stack frame triggering the failure for every failure is 182difficult. 183