C Standard Library assert.h

What You’ll Learn

The <assert.h> header provides the assert macro—a simple debugging tool that verifies assumptions in your code. When a check fails, you get a clear error message and the program stops immediately so you can fix the bug early.

Definition and Usage

assert(expression) tests whether expression is non-zero (true). If it evaluates to zero (false), the implementation prints a diagnostic to stderr (typically including the expression, file name, and line number) and calls abort() to terminate the program.

Use assert to document assumptions that must hold if your code is correct—non-null pointers after allocation, valid array indices, preconditions on function arguments. It is a development aid, not a substitute for handling recoverable errors from users or the OS.

📝 Syntax

Include the header and use the macro:

#include <assert.h>

assert(expression);

Macro defined in assert.h

• assert(expression) — if expression is false (zero), print diagnostic and call abort(). If true (non-zero), no effect.

Disabling assertions

#define NDEBUG          /* define before #include <assert.h> */
#include <assert.h>

/* Or compile: gcc -DNDEBUG ... */

Parameters

• expression — any scalar expression with a value comparable to zero. Common forms: ptr != NULL, n >= 0, index < size.

Headers and linking

• #include <assert.h>
• No special link flag required (unlike math.h).
• Compile: gcc program.c -std=c11 -o program

Examples Gallery

Compile debug examples without NDEBUG to see assertions fire. Use gcc file.c -std=c11 -g -o out for clear line numbers in failure messages.

#include <assert.h>
#include <math.h>
#include <stdio.h>

double calculate_sqrt(double number) {
    assert(number >= 0);
    return sqrt(number);
}

int main(void) {
    printf("sqrt(25) = %.2f\n", calculate_sqrt(25.0));
    printf("sqrt(-4) = %.2f\n", calculate_sqrt(-4.0));

    return 0;
}

sqrt(25) = 5.00
a.out: assert_sqrt.c:6: calculate_sqrt: Assertion `number >= 0' failed.

#include <assert.h>
#include <stdio.h>

void print_length(const char *text) {
    assert(text != NULL);
    printf("Length check: first char is '%c'\n", text[0]);
}

int main(void) {
    print_length("hello");
    print_length(NULL);

    return 0;
}

Length check: first char is 'h'
a.out: assert_ptr.c:5: print_length: Assertion `text != NULL' failed.

#include <assert.h>
#include <stdio.h>

int get_item(const int *arr, size_t len, size_t index) {
    assert(arr != NULL);
    assert(index < len);
    return arr[index];
}

int main(void) {
    int data[] = { 10, 20, 30 };

    printf("data[1] = %d\n", get_item(data, 3, 1));
    printf("data[5] = %d\n", get_item(data, 3, 5));

    return 0;
}

data[1] = 20
a.out: assert_bounds.c:6: get_item: Assertion `index < len' failed.

/* Debug build:   gcc assert_ndebug.c -std=c11 -g -o debug */
/* Release build: gcc -DNDEBUG assert_ndebug.c -std=c11 -O2 -o release */

#include <assert.h>
#include <stdio.h>

int main(void) {
    int secret = 0;

    assert((secret = 42));  /* side effect — avoid this pattern! */
    printf("secret = %d\n", secret);

    return 0;
}

Debug build:   secret = 42
Release build: secret = 0   (assert removed; assignment never ran)

#include <assert.h>
#include <stdio.h>

int parse_positive(int n) {
    if (n <= 0) {
        return -1;   /* user gave bad input — recoverable */
    }
    assert(n > 0);   /* internal invariant after the check */
    return n * 2;
}

int main(void) {
    int result;

    result = parse_positive(5);
    printf("parse_positive(5)  = %d\n", result);

    result = parse_positive(-1);
    printf("parse_positive(-1) = %d (error code)\n", result);

    return 0;
}

parse_positive(5)  = 10
parse_positive(-1) = -1 (error code)

🚀 Common Use Cases

• Function preconditions — arguments must satisfy contracts (non-null, in range).
• Postconditions — result of a function meets expectations before return.
• Loop invariants — index stays within bounds each iteration during development.
• Unreachable code — assert(0 && "should not reach here") after a full switch.
• Unit testing aid — catch logic errors early while writing tests.
• Documentation — assertions spell out assumptions readers might miss.

📝 Notes

• assert is a macro, not a function—no guaranteed stack frame or single evaluation when NDEBUG is set.
• Define NDEBUG before #include <assert.h> to disable all assertions.
• Failed assert calls abort()—not recoverable; unsuitable for user input errors.
• Do not put side effects inside assert(expression).
• static_assert (C11) is separate—compile-time only, keyword not in assert.h.
• Assertion messages and exact format vary slightly by compiler (GCC, Clang, MSVC).

⚡ Optimization

In debug builds, assert adds a branch and possibly string data at each site. That is acceptable during development. For release builds, compile with -DNDEBUG (or -O2 projects that define it) so assertions compile out entirely—zero runtime cost.

Avoid dense assert calls in inner loops on hot paths even in debug builds; prefer checking invariants at function entry or less frequently.

💡 Best Practices