# Clang 8 documentation

## Sanitizer special case list

- Introduction
- Goal and usage
- Example
- Format

## Introduction

This document describes the way to disable or alter the behavior of sanitizer tools for certain source-level entities by providing a special file at compile-time.

## Goal and usage

User of sanitizer tools, such as AddressSanitizer, ThreadSanitizer or MemorySanitizer may want to disable or alter some checks for certain source-level entities to:

- speedup hot function, which is known to be correct;
- ignore a function that does some low-level magic (e.g. walks through the thread stack, bypassing the frame boundaries);
- ignore a known problem.

To achieve this, user may create a file listing the entities they want to ignore, and pass it to clang at compile-time using `-fsanitize-blacklist` flag. See Clang Compiler User’s Manual for details.

## Example

    $ cat foo.c
    #include <stdlib.h>
    void bad_foo() {
      int *a = (int*)malloc(40);
      a[10] = 1;
    }
    int main() { bad_foo(); }
    $ cat blacklist.txt
    # Ignore reports from bad_foo function.
    fun:bad_foo
    $ clang -fsanitize=address foo.c ; ./a.out
    # AddressSanitizer prints an error report.
    $ clang -fsanitize=address -fsanitize-blacklist=blacklist.txt foo.c ; ./a.out
    # No error report here.

## Format

Blacklists consist of entries, optionally grouped into sections. Empty lines and lines starting with “#” are ignored.

Section names are regular expressions written in square brackets that denote which sanitizer the following entries apply to. For example, `[address]` specifies AddressSanitizer while `[cfi-vcall|cfi-icall]` specifies Control Flow Integrity virtual and indirect call checking. Entries without a section will be placed under the `[*]` section applying to all enabled sanitizers.

Entries contain an entity type, followed by a colon and a regular expression, specifying the names of the entities, optionally followed by an equals sign and a tool-specific category, e.g. `fun:*ExampleFunc=example_category`. The meaning of `*` in regular expression for entity names is different - it is treated as in shell wildcarding. Two generic entity types are `src` and `fun`, which allow users to specify source files and functions, respectively. Some sanitizer tools may introduce custom entity types and categories - refer to tool-specific docs.

    # Lines starting with # are ignored.
    # Turn off checks for the source file (use absolute path or path relative
    # to the current working directory):
    src:/path/to/source/file.c
    # Turn off checks for a particular functions (use mangled names):
    fun:MyFooBar
    fun:_Z8MyFooBarv
    # Extended regular expressions are supported:
    fun:bad_(foo|bar)
    src:bad_source[1-9].c
    # Shell like usage of * is supported (* is treated as .*):
    src:bad/sources/*
    fun:*BadFunction*
    # Specific sanitizer tools may introduce categories.
    src:/special/path/*=special_sources
    # Sections can be used to limit blacklist entries to specific sanitizers
    [address]
    fun:*BadASanFunc*
    # Section names are regular expressions
    [cfi-vcall|cfi-icall]
    fun:*BadCfiCall
    # Entries without sections are placed into [*] and apply to all sanitizers