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 Users of sanitizer tools, such as :doc:`AddressSanitizer`,
  19 :doc:`HardwareAssistedAddressSanitizerDesign`, :doc:`ThreadSanitizer`,
  20 :doc:`MemorySanitizer` or :doc:`UndefinedBehaviorSanitizer` may want to disable
  21 or alter some checks for certain source-level entities to:
  22
  23 * speedup hot function, which is known to be correct;
  24 * ignore a function that does some low-level magic (e.g. walks through the
  25   thread stack, bypassing the frame boundaries);
  26 * ignore a known problem.
  27
  28 To achieve this, user may create a file listing the entities they want to
  29 ignore, and pass it to clang at compile-time using
  30 ``-fsanitize-ignorelist`` flag. See :doc:`UsersManual` for details.
  31
  32 Example
  33 =======
  34
  35 .. code-block:: bash
  36
  37   $ cat foo.c
  38   #include <stdlib.h>
  39   void bad_foo() {
  40     int *a = (int*)malloc(40);
  41     a[10] = 1;
  42   }
  43   int main() { bad_foo(); }
  44   $ cat ignorelist.txt
  45   # Ignore reports from bad_foo function.
  46   fun:bad_foo
  47   $ clang -fsanitize=address foo.c ; ./a.out
  48   # AddressSanitizer prints an error report.
  49   $ clang -fsanitize=address -fsanitize-ignorelist=ignorelist.txt foo.c ; ./a.out
  50   # No error report here.
  51
  52 Usage with UndefinedBehaviorSanitizer
  53 =====================================
  54
  55 ``unsigned-integer-overflow``, ``signed-integer-overflow``,
  56 ``implicit-signed-integer-truncation``,
  57 ``implicit-unsigned-integer-truncation``, and ``enum`` sanitizers support the
  58 ability to adjust instrumentation based on type.
  59
  60 By default, supported sanitizers will have their instrumentation disabled for
  61 types specified within an ignorelist.
  62
  63 .. code-block:: bash
  64
  65   $ cat foo.c
  66   void foo() {
  67     int a = 2147483647; // INT_MAX
  68     ++a;                // Normally, an overflow with -fsanitize=signed-integer-overflow
  69   }
  70   $ cat ignorelist.txt
  71   [signed-integer-overflow]
  72   type:int
  73   $ clang -fsanitize=signed-integer-overflow -fsanitize-ignorelist=ignorelist.txt foo.c ; ./a.out
  74   # no signed-integer-overflow error
  75
  76 For example, supplying the above ``ignorelist.txt`` to
  77 ``-fsanitize-ignorelist=ignorelist.txt`` disables overflow sanitizer
  78 instrumentation for arithmetic operations containing values of type ``int``.
  79
  80 The ``=sanitize`` category is also supported. Any types assigned to the
  81 ``sanitize`` category will have their sanitizer instrumentation remain. If the
  82 same type appears within or across ignorelists with different categories the
  83 ``sanitize`` category takes precedence -- regardless of order.
  84
  85 With this, one may disable instrumentation for some or all types and
  86 specifically allow instrumentation for one or many types -- including types
  87 created via ``typedef``. This is a way to achieve a sort of "allowlist" for
  88 supported sanitizers.
  89
  90 .. code-block:: bash
  91
  92   $ cat ignorelist.txt
  93   [implicit-signed-integer-truncation]
  94   type:*
  95   type:T=sanitize
  96
  97   $ cat foo.c
  98   typedef char T;
  99   typedef char U;
 100   void foo(int toobig) {
 101     T a = toobig;    // instrumented
 102     U b = toobig;    // not instrumented
 103     char c = toobig; // also not instrumented
 104   }
 105
 106 Format
 107 ======
 108
 109 Ignorelists consist of entries, optionally grouped into sections. Empty lines
 110 and lines starting with "#" are ignored.
 111
 112 .. note::
 113
 114   Prior to Clang 18, section names and entries described below use a variant of
 115   regex where ``*`` is translated to ``.*``. Clang 18 (`D154014
 116   <https://reviews.llvm.org/D154014>`) switches to glob and plans to remove
 117   regex support in Clang 19.
 118
 119   For Clang 18, regex is supported if ``#!special-case-list-v1`` is the first
 120   line of the file.
 121
 122   Many special case lists use ``.`` to indicate the literal character and do
 123   not use regex metacharacters such as ``(``, ``)``. They are unaffected by the
 124   regex to glob transition. For more details, see `this discourse post
 125   <https://discourse.llvm.org/t/use-glob-instead-of-regex-for-specialcaselists/71666>`_.
 126
 127 Section names are globs written in square brackets that denote
 128 which sanitizer the following entries apply to. For example, ``[address]``
 129 specifies AddressSanitizer while ``[{cfi-vcall,cfi-icall}]`` specifies Control
 130 Flow Integrity virtual and indirect call checking. Entries without a section
 131 will be placed under the ``[*]`` section applying to all enabled sanitizers.
 132
 133 Entries contain an entity type, followed by a colon and a glob,
 134 specifying the names of the entities, optionally followed by an equals sign and
 135 a tool-specific category, e.g. ``fun:*ExampleFunc=example_category``.
 136 Two generic entity types are ``src`` and
 137 ``fun``, which allow users to specify source files and functions, respectively.
 138 Some sanitizer tools may introduce custom entity types and categories - refer to
 139 tool-specific docs.
 140
 141 .. code-block:: bash
 142
 143     # The line above is explained in the note above
 144     # Lines starting with # are ignored.
 145     # Turn off checks for the source file
 146     # Entries without sections are placed into [*] and apply to all sanitizers
 147     src:path/to/source/file.c
 148     src:*/source/file.c
 149     # Turn off checks for this main file, including files included by it.
 150     # Useful when the main file instead of an included file should be ignored.
 151     mainfile:file.c
 152     # Turn off checks for a particular functions (use mangled names):
 153     fun:_Z8MyFooBarv
 154     # Glob brace expansions and character ranges are supported
 155     fun:bad_{foo,bar}
 156     src:bad_source[1-9].c
 157     # "*" matches zero or more characters
 158     src:bad/sources/*
 159     fun:*BadFunction*
 160     # Specific sanitizer tools may introduce categories.
 161     src:/special/path/*=special_sources
 162     # Sections can be used to limit ignorelist entries to specific sanitizers
 163     [address]
 164     fun:*BadASanFunc*
 165     # Section names are globs
 166     [{cfi-vcall,cfi-icall}]
 167     fun:*BadCfiCall
 168
 169 ``mainfile`` is similar to applying ``-fno-sanitize=`` to a set of files but
 170 does not need plumbing into the build system. This works well for internal
 171 linkage functions but has a caveat for C++ vague linkage functions.
 172
 173 C++ vague linkage functions (e.g. inline functions, template instantiations) are
 174 deduplicated at link time. A function (in an included file) ignored by a
 175 specific ``mainfile`` pattern may not be the prevailing copy picked by the
 176 linker. Therefore, using ``mainfile`` requires caution. It may still be useful,
 177 e.g. when patterns are picked in a way to ensure the prevailing one is ignored.
 178 (There is action-at-a-distance risk.)
 179
 180 ``mainfile`` can be useful enabling a ubsan check for a large code base when
 181 finding the direct stack frame triggering the failure for every failure is
 182 difficult.