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:
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:
#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:
==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
int add_one(int x) { return x + 1; } /* called with INT_MAX */
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
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-symbolizeron the path orASAN_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,addressin Clang). - Specific checks.
-fsanitize=bounds,-fsanitize=signed-integer-overflow,-fsanitize=nulland 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.
Related
- Valgrind for memory checking without recompiling
- Debugging with gdb and Compilers
- Undefined behavior catalog and Memory errors
- Tutorial: Debugging and Memory errors