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