1*67e74705SXin Li=========================== 2*67e74705SXin LiSanitizer special case list 3*67e74705SXin Li=========================== 4*67e74705SXin Li 5*67e74705SXin Li.. contents:: 6*67e74705SXin Li :local: 7*67e74705SXin Li 8*67e74705SXin LiIntroduction 9*67e74705SXin Li============ 10*67e74705SXin Li 11*67e74705SXin LiThis document describes the way to disable or alter the behavior of 12*67e74705SXin Lisanitizer tools for certain source-level entities by providing a special 13*67e74705SXin Lifile at compile-time. 14*67e74705SXin Li 15*67e74705SXin LiGoal and usage 16*67e74705SXin Li============== 17*67e74705SXin Li 18*67e74705SXin LiUser of sanitizer tools, such as :doc:`AddressSanitizer`, :doc:`ThreadSanitizer` 19*67e74705SXin Lior :doc:`MemorySanitizer` may want to disable or alter some checks for 20*67e74705SXin Licertain source-level entities to: 21*67e74705SXin Li 22*67e74705SXin Li* speedup hot function, which is known to be correct; 23*67e74705SXin Li* ignore a function that does some low-level magic (e.g. walks through the 24*67e74705SXin Li thread stack, bypassing the frame boundaries); 25*67e74705SXin Li* ignore a known problem. 26*67e74705SXin Li 27*67e74705SXin LiTo achieve this, user may create a file listing the entities they want to 28*67e74705SXin Liignore, and pass it to clang at compile-time using 29*67e74705SXin Li``-fsanitize-blacklist`` flag. See :doc:`UsersManual` for details. 30*67e74705SXin Li 31*67e74705SXin LiExample 32*67e74705SXin Li======= 33*67e74705SXin Li 34*67e74705SXin Li.. code-block:: bash 35*67e74705SXin Li 36*67e74705SXin Li $ cat foo.c 37*67e74705SXin Li #include <stdlib.h> 38*67e74705SXin Li void bad_foo() { 39*67e74705SXin Li int *a = (int*)malloc(40); 40*67e74705SXin Li a[10] = 1; 41*67e74705SXin Li } 42*67e74705SXin Li int main() { bad_foo(); } 43*67e74705SXin Li $ cat blacklist.txt 44*67e74705SXin Li # Ignore reports from bad_foo function. 45*67e74705SXin Li fun:bad_foo 46*67e74705SXin Li $ clang -fsanitize=address foo.c ; ./a.out 47*67e74705SXin Li # AddressSanitizer prints an error report. 48*67e74705SXin Li $ clang -fsanitize=address -fsanitize-blacklist=blacklist.txt foo.c ; ./a.out 49*67e74705SXin Li # No error report here. 50*67e74705SXin Li 51*67e74705SXin LiFormat 52*67e74705SXin Li====== 53*67e74705SXin Li 54*67e74705SXin LiEach line contains an entity type, followed by a colon and a regular 55*67e74705SXin Liexpression, specifying the names of the entities, optionally followed by 56*67e74705SXin Lian equals sign and a tool-specific category. Empty lines and lines starting 57*67e74705SXin Liwith "#" are ignored. The meanining of ``*`` in regular expression for entity 58*67e74705SXin Linames is different - it is treated as in shell wildcarding. Two generic 59*67e74705SXin Lientity types are ``src`` and ``fun``, which allow user to add, respectively, 60*67e74705SXin Lisource files and functions to special case list. Some sanitizer tools may 61*67e74705SXin Liintroduce custom entity types - refer to tool-specific docs. 62*67e74705SXin Li 63*67e74705SXin Li.. code-block:: bash 64*67e74705SXin Li 65*67e74705SXin Li # Lines starting with # are ignored. 66*67e74705SXin Li # Turn off checks for the source file (use absolute path or path relative 67*67e74705SXin Li # to the current working directory): 68*67e74705SXin Li src:/path/to/source/file.c 69*67e74705SXin Li # Turn off checks for a particular functions (use mangled names): 70*67e74705SXin Li fun:MyFooBar 71*67e74705SXin Li fun:_Z8MyFooBarv 72*67e74705SXin Li # Extended regular expressions are supported: 73*67e74705SXin Li fun:bad_(foo|bar) 74*67e74705SXin Li src:bad_source[1-9].c 75*67e74705SXin Li # Shell like usage of * is supported (* is treated as .*): 76*67e74705SXin Li src:bad/sources/* 77*67e74705SXin Li fun:*BadFunction* 78*67e74705SXin Li # Specific sanitizer tools may introduce categories. 79*67e74705SXin Li src:/special/path/*=special_sources 80