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`, :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 .. note::
  58
  59   Prior to Clang 18, section names and entries described below use a variant of
  60   regex where ``*`` is translated to ``.*``. Clang 18 (`D154014
  61   <https://reviews.llvm.org/D154014>`) switches to glob and plans to remove
  62   regex support in Clang 19.
  63
  64   For Clang 18, regex is supported if ``#!special-case-list-v1`` is the first
  65   line of the file.
  66
  67   Many special case lists use ``.`` to indicate the literal character and do
  68   not use regex metacharacters such as ``(``, ``)``. They are unaffected by the
  69   regex to glob transition. For more details, see `this discourse post
  70   <https://discourse.llvm.org/t/use-glob-instead-of-regex-for-specialcaselists/71666>`_.
  71
  72 Section names are globs written in square brackets that denote
  73 which sanitizer the following entries apply to. For example, ``[address]``
  74 specifies AddressSanitizer while ``[{cfi-vcall,cfi-icall}]`` specifies Control
  75 Flow Integrity virtual and indirect call checking. Entries without a section
  76 will be placed under the ``[*]`` section applying to all enabled sanitizers.
  77
  78 Entries contain an entity type, followed by a colon and a glob,
  79 specifying the names of the entities, optionally followed by an equals sign and
  80 a tool-specific category, e.g. ``fun:*ExampleFunc=example_category``.
  81 Two generic entity types are ``src`` and
  82 ``fun``, which allow users to specify source files and functions, respectively.
  83 Some sanitizer tools may introduce custom entity types and categories - refer to
  84 tool-specific docs.
  85
  86 .. code-block:: bash
  87
  88     # The line above is explained in the note above
  89     # Lines starting with # are ignored.
  90     # Turn off checks for the source file
  91     # Entries without sections are placed into [*] and apply to all sanitizers
  92     src:path/to/source/file.c
  93     src:*/source/file.c
  94     # Turn off checks for this main file, including files included by it.
  95     # Useful when the main file instead of an included file should be ignored.
  96     mainfile:file.c
  97     # Turn off checks for a particular functions (use mangled names):
  98     fun:_Z8MyFooBarv
  99     # Glob brace expansions and character ranges are supported
 100     fun:bad_{foo,bar}
 101     src:bad_source[1-9].c
 102     # "*" matches zero or more characters
 103     src:bad/sources/*
 104     fun:*BadFunction*
 105     # Specific sanitizer tools may introduce categories.
 106     src:/special/path/*=special_sources
 107     # Sections can be used to limit ignorelist entries to specific sanitizers
 108     [address]
 109     fun:*BadASanFunc*
 110     # Section names are globs
 111     [{cfi-vcall,cfi-icall}]
 112     fun:*BadCfiCall
 113
 114 ``mainfile`` is similar to applying ``-fno-sanitize=`` to a set of files but
 115 does not need plumbing into the build system. This works well for internal
 116 linkage functions but has a caveat for C++ vague linkage functions.
 117
 118 C++ vague linkage functions (e.g. inline functions, template instantiations) are
 119 deduplicated at link time. A function (in an included file) ignored by a
 120 specific ``mainfile`` pattern may not be the prevailing copy picked by the
 121 linker. Therefore, using ``mainfile`` requires caution. It may still be useful,
 122 e.g. when patterns are picked in a way to ensure the prevailing one is ignored.
 123 (There is action-at-a-distance risk.)
 124
 125 ``mainfile`` can be useful enabling a ubsan check for a large code base when
 126 finding the direct stack frame triggering the failure for every failure is
 127 difficult.