1 =========================== 2 Sanitizer special case list 3 =========================== 4 5 .. contents:: 6 :local: 7 8 Introduction 9 ============ 10 11 This document describes the way to disable or alter the behavior of 12 sanitizer tools for certain source-level entities by providing a special 13 file at compile-time. 14 15 Goal and usage 16 ============== 17 18 User of sanitizer tools, such as :doc:`AddressSanitizer`, :doc:`ThreadSanitizer` 19 or :doc:`MemorySanitizer` may want to disable or alter some checks for 20 certain 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 27 To achieve this, user may create a file listing the entities they want to 28 ignore, and pass it to clang at compile-time using 29 ``-fsanitize-blacklist`` flag. See :doc:`UsersManual` for details. 30 31 Example 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 51 Format 52 ====== 53 54 Each line contains an entity type, followed by a colon and a regular 55 expression, specifying the names of the entities, optionally followed by 56 an equals sign and a tool-specific category. Empty lines and lines starting 57 with "#" are ignored. The meanining of ``*`` in regular expression for entity 58 names is different - it is treated as in shell wildcarding. Two generic 59 entity types are ``src`` and ``fun``, which allow user to add, respectively, 60 source files and functions to special case list. Some sanitizer tools may 61 introduce custom entity types - refer to tool-specific docs. 62 63 .. code-block:: bash 64 65 # Lines starting with # are ignored. 66 # Turn off checks for the source file (use absolute path or path relative 67 # to the current working directory): 68 src:/path/to/source/file.c 69 # Turn off checks for a particular functions (use mangled names): 70 fun:MyFooBar 71 fun:_Z8MyFooBarv 72 # Extended regular expressions are supported: 73 fun:bad_(foo|bar) 74 src:bad_source[1-9].c 75 # Shell like usage of * is supported (* is treated as .*): 76 src:bad/sources/* 77 fun:*BadFunction* 78 # Specific sanitizer tools may introduce categories. 79 src:/special/path/*=special_sources 80
