Article

Undefined Behavior Sanitizer

Discover and fix undefined behavior in your code.

Overview

The Undefined Behavior Sanitizer, or UBSan, is an LLVM tool for C languages that detects undefined behavior at runtime. Undefined behavior describes the result of any operation with unspecified semantics, such as dividing by zero, loading memory from a misaligned pointer, or dereferencing a null pointer.

When a program has undefined behavior, it may cause a crash, incorrect program output, or no problem at all. It can also make a program function differently depending on the version of a compiler that was used. For these reasons, undefined behavior should be avoided.

How UBSan Works

The Undefined Behavior Sanitizer works by using Clang to emit checks into your code during compilation. The nature of the inserted code depends on the kind of undefined behavior being checked for. For example, the Integer Overflow check adds code around arithmetic operators, including addition, subtraction, multiplication, and division.

// Before
int32_t n = 42;
n += 17;

// After
int32_t n = 42;
if (SignedAdditionWillOverflow(n, 17)) {
    DiagnoseUndefinedBehavior();
}
n += 17;

Performance Impact

The performance impact of the Undefined Behavior Sanitizer is minimal, with with an average 20% CPU overhead in the Debug configuration.

Topics

First Steps

Enabling the Undefined Behavior Sanitizer

Configure your Xcode scheme to check for undefined behavior at runtime.

Undefined Behavior Checks

Misaligned Pointer

Detects when code accesses a misaligned pointer or creates a misaligned reference.

Invalid Boolean

Detects when a program accesses a Boolean variable and its value isn’t true or false.

Out-of-Bounds Array Access

Detects out-of-bounds access of arrays.

Invalid Enumeration Value

Detects when an enumeration variable has an invalid value.

Reaching of Unreachable Point

Detects when a program reaches an unreachable point.

Dynamic Type Violation

Detects when an object has the wrong dynamic type.

Invalid Float Cast

Detects out-of-range casts to, from, or between floating-point types.

Division by Zero

Detects division where the divisor is zero.

Nonnull Argument Violation

Detects when a null value is incorrectly passed as an argument.

Nonnull Return Value Violation

Detects when a function incorrectly returns a null value.

Nonnull Variable Assignment Violation

Detects when a null value is incorrectly assigned to a variable .

Null Reference Creation and Null Pointer Dereference

Detects the creation of null references and null pointer dereferences.

Invalid Object Size

Detects invalid pointer casts due to differences in the sizes of types.

Invalid Shift

Detects invalid and overflowing shifts.

Integer Overflow

Detects overflow in arithmetic.

Invalid Variable-Length Array

Detects array bounds that aren't positive.

Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.

Learn more about using Apple's beta software