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-blacklist`` 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 blacklist.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-blacklist=blacklist.txt foo.c ; ./a.out 49 # No error report here. 50 51Format 52====== 53 54Blacklists consist of entries, optionally grouped into sections. Empty lines and 55lines 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 a particular functions (use mangled names): 79 fun:MyFooBar 80 fun:_Z8MyFooBarv 81 # Extended regular expressions are supported: 82 fun:bad_(foo|bar) 83 src:bad_source[1-9].c 84 # Shell like usage of * is supported (* is treated as .*): 85 src:bad/sources/* 86 fun:*BadFunction* 87 # Specific sanitizer tools may introduce categories. 88 src:/special/path/*=special_sources 89 # Sections can be used to limit blacklist entries to specific sanitizers 90 [address] 91 fun:*BadASanFunc* 92 # Section names are regular expressions 93 [cfi-vcall|cfi-icall] 94 fun:*BadCfiCall 95 # Entries without sections are placed into [*] and apply to all sanitizers 96