Sanitizers and safety

Purpose

Zig ships several runtime-checked safety features. Some are intrinsic to the language (integer overflow, slice bounds, optional unwrap). Others are imported from the LLVM ecosystem (UBSan, ThreadSanitizer). This page maps where each lives.

Language-level safety

Modes — set per build (-O Debug / ReleaseSafe / ReleaseFast / ReleaseSmall) — control which checks are emitted:

Check	Where it lives
Integer overflow / underflow	src/Sema.zig lowers checked-arithmetic AIR; backends emit branches; runtime panic.
Slice / array index	Same path: AIR includes a bounds check that lowers to a panic on failure.
Optional unwrap of null	AIR OptUnwrap instruction with safety check.
error payload unwrap	Similar.
Unreachable	unreachable traps in safe modes.
Pointer alignment	Compile-time when possible, runtime checks when needed.
Float division by zero	Sema/arith.zig lowers to checked division.

The panic path goes through std.builtin.default_panic, which is overridable. The compiler itself overrides it with crash_report.panic (see Debugging).

UBSan-style runtime

lib/ubsan_rt.zig (~22 KB) implements UBSan helpers (__ubsan_handle_*). It is linked when UBSan is enabled. The code paths producing the calls are emitted by either clang (for C input) or the Zig backend (for the language-level checks).

ThreadSanitizer

lib/libtsan/ carries the bundled TSan runtime sources (this is upstream LLVM's compiler-rt/lib/tsan/). When the user passes -fsanitize=thread to zig cc/zig c++ or the equivalent build option, this is the runtime that gets linked.

Stack traces

std.debug.dumpCurrentStackTrace, std.debug.captureCurrentStackTrace, and the panic handler all rely on:

• Debug info (DWARF on Linux, Mach-O DWARF on macOS, PDB on Windows) read by lib/std/debug.zig and lib/std/dwarf.zig / lib/std/pdb.zig.
• The unwinder in lib/libunwind/ for languages that use it (mostly C++).
• std.Options.allow_stack_tracing to opt out of the machinery in size-constrained builds.

compiler-rt safety helpers

lib/compiler_rt/ includes the helpers needed to implement safety checks on architectures without hardware support: 64×64 multiplication overflow checks, 128-bit arithmetic, soft-float comparisons. See Compiler runtime.

Tests

• test/cases/safety/ — fixtures asserting that each safety check fires in safe modes and is elided in ReleaseFast.
• test/error_traces.zig and test/stack_traces.zig — formatting and content checks for stack traces.
• test/behavior/ — behavioral tests covering checked arithmetic, optional unwraps, etc.

Entry points for modification

• New language safety check: the relevant Sema site, the corresponding AIR instruction, every backend, and a fixture under test/cases/safety/.
• UBSan handler: lib/ubsan_rt.zig.
• Stack-trace formatting: lib/std/debug.zig.

See Debugging for what to do when a safety check fires unexpectedly.