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 54Each line contains an entity type, followed by a colon and a regular 55expression, specifying the names of the entities, optionally followed by 56an equals sign and a tool-specific category. Empty lines and lines starting 57with "#" are ignored. The meanining of ``*`` in regular expression for entity 58names is different - it is treated as in shell wildcarding. Two generic 59entity types are ``src`` and ``fun``, which allow user to add, respectively, 60source files and functions to special case list. Some sanitizer tools may 61introduce 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