Home | History | Annotate | Line # | Download | only in docs 
      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-ignorelist`` 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 ignorelist.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-ignorelist=ignorelist.txt foo.c ; ./a.out
     49   # No error report here.
     50 
     51 Format
     52 ======
     53 
     54 Ignorelists consist of entries, optionally grouped into sections. Empty lines
     55 and 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 ignorelist 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