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 18User of sanitizer tools, such as :doc:`AddressSanitizer`, :doc:`ThreadSanitizer` 19or :doc:`MemorySanitizer` may want to disable or alter some checks for 20certain source-level entities to: 21 22* speedup hot function, which is known to be correct; 23* ignore a function that does some low-level magic (e.g. walks through the 24 thread stack, bypassing the frame boundaries); 25* ignore a known problem. 26 27To achieve this, user may create a file listing the entities they want to 28ignore, and pass it to clang at compile-time using 29``-fsanitize-ignorelist`` flag. See :doc:`UsersManual` for details. 30 31Example 32======= 33 34.. code-block:: bash 35 36 $ cat foo.c 37 #include <stdlib.h> 38 void bad_foo() { 39 int *a = (int*)malloc(40); 40 a[10] = 1; 41 } 42 int main() { bad_foo(); } 43 $ cat ignorelist.txt 44 # Ignore reports from bad_foo function. 45 fun:bad_foo 46 $ clang -fsanitize=address foo.c ; ./a.out 47 # AddressSanitizer prints an error report. 48 $ clang -fsanitize=address -fsanitize-ignorelist=ignorelist.txt foo.c ; ./a.out 49 # No error report here. 50 51Format 52====== 53 54Ignorelists consist of entries, optionally grouped into sections. Empty lines 55and lines starting with "#" are ignored. 56 57Section names are regular expressions written in square brackets that denote 58which sanitizer the following entries apply to. For example, ``[address]`` 59specifies AddressSanitizer while ``[cfi-vcall|cfi-icall]`` specifies Control 60Flow Integrity virtual and indirect call checking. Entries without a section 61will be placed under the ``[*]`` section applying to all enabled sanitizers. 62 63Entries contain an entity type, followed by a colon and a regular expression, 64specifying the names of the entities, optionally followed by an equals sign and 65a tool-specific category, e.g. ``fun:*ExampleFunc=example_category``. The 66meaning of ``*`` in regular expression for entity names is different - it is 67treated as in shell wildcarding. Two generic entity types are ``src`` and 68``fun``, which allow users to specify source files and functions, respectively. 69Some sanitizer tools may introduce custom entity types and categories - refer to 70tool-specific docs. 71 72.. code-block:: bash 73 74 # Lines starting with # are ignored. 75 # Turn off checks for the source file (use absolute path or path relative 76 # to the current working directory): 77 src:/path/to/source/file.c 78 # Turn off checks for this main file, including files included by it. 79 # Useful when the main file instead of an included file should be ignored. 80 mainfile:file.c 81 # Turn off checks for a particular functions (use mangled names): 82 fun:MyFooBar 83 fun:_Z8MyFooBarv 84 # Extended regular expressions are supported: 85 fun:bad_(foo|bar) 86 src:bad_source[1-9].c 87 # Shell like usage of * is supported (* is treated as .*): 88 src:bad/sources/* 89 fun:*BadFunction* 90 # Specific sanitizer tools may introduce categories. 91 src:/special/path/*=special_sources 92 # Sections can be used to limit ignorelist entries to specific sanitizers 93 [address] 94 fun:*BadASanFunc* 95 # Section names are regular expressions 96 [cfi-vcall|cfi-icall] 97 fun:*BadCfiCall 98 # Entries without sections are placed into [*] and apply to all sanitizers 99 100``mainfile`` is similar to applying ``-fno-sanitize=`` to a set of files but 101does not need plumbing into the build system. This works well for internal 102linkage functions but has a caveat for C++ vague linkage functions. 103 104C++ vague linkage functions (e.g. inline functions, template instantiations) are 105deduplicated at link time. A function (in an included file) ignored by a 106specific ``mainfile`` pattern may not be the prevailing copy picked by the 107linker. Therefore, using ``mainfile`` requires caution. It may still be useful, 108e.g. when patterns are picked in a way to ensure the prevailing one is ignored. 109(There is action-at-a-distance risk.) 110 111``mainfile`` can be useful enabling a ubsan check for a large code base when 112finding the direct stack frame triggering the failure for every failure is 113difficult. 114