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