clang/docs/SanitizerSpecialCaseList.rst

   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 Blacklists consist of entries, optionally grouped into sections. Empty lines and
  55 lines starting with "#" are ignored.
  56
  57 Section names are regular expressions written in square brackets that denote
  58 which sanitizer the following entries apply to. For example, ``[address]``
  59 specifies AddressSanitizer while ``[cfi-vcall|cfi-icall]`` specifies Control
  60 Flow Integrity virtual and indirect call checking. Entries without a section
  61 will be placed under the ``[*]`` section applying to all enabled sanitizers.
  62
  63 Entries contain an entity type, followed by a colon and a regular expression,
  64 specifying the names of the entities, optionally followed by an equals sign and
  65 a tool-specific category, e.g. ``fun:*ExampleFunc=example_category``.  The
  66 meaning of ``*`` in regular expression for entity names is different - it is
  67 treated as in shell wildcarding. Two generic entity types are ``src`` and
  68 ``fun``, which allow users to specify source files and functions, respectively.
  69 Some sanitizer tools may introduce custom entity types and categories - refer to
  70 tool-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