Skip to content
Tutorials Center
My learning

Topics

C Reference ยท Concepts and Tools

Sanitizers: ASan, UBSan and TSan

Reference for GCC and Clang sanitizers: build with ASan, UBSan, TSan and MSan flags, read their reports, set options, and learn what each one can and cannot find.

A sanitizer is a compiler feature that adds checks to your program while it is being built. When the checks find a bug at run time, such as a write past the end of an array or a signed overflow, the program stops with a report that names the kind of error, the source line and often the line where the memory was allocated or freed.

Sanitizers turn silent undefined behavior into loud, precise failures. They are the first tool to reach for when a C program misbehaves in a way you cannot explain, and they belong in your automated tests.

Sanitizer runs need a real shell with GCC or Clang and are read-only on this site: our online runner cannot show their reports. The commands and the reports below are what you will see on your own machine. The one runnable example on this page builds a tiny guard-byte checker in plain C to show the idea behind them.

Quick reference

Sanitizer Flag Finds Typical cost
AddressSanitizer (ASan) -fsanitize=address out-of-bounds access on heap, stack and globals; use after free; double free; invalid free; (with leak checking on Linux) memory leaks about 2x slower, 2-3x memory
UndefinedBehaviorSanitizer (UBSan) -fsanitize=undefined signed overflow, bad shifts, division by zero, null and misaligned pointers, invalid enum or bool values, out-of-bounds array index (with known bounds), unreachable reached small
ThreadSanitizer (TSan) -fsanitize=thread data races, some lock-order problems 5-15x slower, 5-10x memory
MemorySanitizer (MSan) -fsanitize=memory (Clang only) reading uninitialized memory about 3x slower
LeakSanitizer (LSan) -fsanitize=leak (also part of ASan on Linux) leaked heap blocks at exit very small

ASan and TSan cannot be combined in one build. ASan and UBSan combine well.

Using them

Compile and link with the flag, keep frame pointers for readable stack traces, and use a low optimization level while debugging:

TEXT
gcc -std=c23 -g -O1 -fno-omit-frame-pointer -Wall -Wextra \
    -fsanitize=address,undefined program.c -o program
./program

Add -fno-sanitize-recover=undefined to stop at the first UBSan error instead of printing it and continuing. Build the whole program, including libraries you compile yourself, with the same flags.

An AddressSanitizer report

For a heap overflow such as this read-only program:

C
#include <stdlib.h>

int main(void) {
    int *values = malloc(4 * sizeof *values);
    values[4] = 1;                 /* one element past the end */
    free(values);
    return 0;
}

ASan prints a report of this shape and exits with a non-zero status:

TEXT
==12345==ERROR: AddressSanitizer: heap-buffer-overflow on address 0x...
WRITE of size 4 at 0x... thread T0
    #0 0x... in main program.c:5
0x... is located 0 bytes after 16-byte region [0x...,0x...)
allocated by thread T0 here:
    #0 0x... in malloc
    #1 0x... in main program.c:4

Read it top to bottom: the kind of bug (heap-buffer-overflow), the access (a 4-byte write), where it happened, and where the block was allocated. Other headings you will meet: stack-buffer-overflow, global-buffer-overflow, heap-use-after-free, attempting double-free, stack-use-after-return and detected memory leaks.

A UBSan report

C
int add_one(int x) { return x + 1; }   /* called with INT_MAX */
TEXT
program.c:1:31: runtime error: signed integer overflow: 2147483647 + 1 cannot be represented in type 'int'

UBSan messages begin with runtime error: and name the exact operation.

Try it

C The idea behind the checkers: guard bytes around a buffer

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.

Options and tips

  • Environment variables configure the runtime: ASAN_OPTIONS=detect_leaks=1:abort_on_error=1, UBSAN_OPTIONS=print_stacktrace=1:halt_on_error=1, TSAN_OPTIONS=second_deadlock_stack=1.
  • Symbolized stack traces need debug info (-g) and, on some systems, llvm-symbolizer on the path or ASAN_SYMBOLIZER_PATH.
  • Tests only. Sanitized builds are slower and use more memory. Keep them in CI and local debugging, not in release builds.
  • Coverage is limited to code that runs. A sanitizer finds a bug only when a test reaches it. Combine with unit tests and fuzzing (-fsanitize=fuzzer,address in Clang).
  • Specific checks. -fsanitize=bounds, -fsanitize=signed-integer-overflow, -fsanitize=null and others enable single UBSan checks. -fsanitize=unsigned-integer-overflow (Clang) flags wrap-around that is legal but suspicious.
  • Windows. MSVC supports ASan with /fsanitize=address; the other sanitizers are available through Clang.
  • They are not security hardening. ASan changes the memory layout and is not meant for production.