Skip to content
Tutorials Center
My learning

Topics

C Reference ยท Preprocessor

The assert macro

Reference for the C assert macro from assert.h: how it aborts on a false condition, how NDEBUG removes it, and when to use static_assert instead.

assert is a macro from <assert.h> that checks a condition while the program runs. If the expression is true, nothing happens. If it is false, the program prints a diagnostic that names the expression, the file, the line and the function, then calls abort().

Use it to document and enforce things that must be true if your code is correct: preconditions, invariants, "this branch cannot happen". It is a debugging aid for programmer mistakes, not a way to handle errors caused by users or the environment.

C
#include <assert.h>

assert(index < length);

Try it

C Passing assertions and a compile-time check

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.

C A failing assertion

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.

Syntax

C
#include <assert.h>

void assert(scalar-expression);   /* a macro, not a function */
Name Description
expression Any expression of scalar type. If it compares equal to zero, the assertion fails.

Behavior when it fails: a message naming the file, line, function and expression (glibc prints main.c:5: divide: Assertion followed by the expression and failed.) is written to stderr, then abort() is called (so the exit status shows termination by SIGABRT). The exact wording is implementation-defined.

NDEBUG: if the macro NDEBUG is defined at the point where <assert.h> is included, assert(x) expands to ((void)0). The expression is not evaluated at all.

Usage notes

  • Never put side effects in an assertion. assert(read_byte() == 0x7f) or assert(i++ < n) change behavior between debug and release builds, because with NDEBUG the expression vanishes. Compute first, assert on the result.
  • Assert on bugs, not on bad input. File not found, bad user input and failed malloc are normal run-time conditions that you must handle with real error checks, since assertions can be compiled out.
  • Adding a message. assert(cond && "explanation") works because a string literal is always true and appears in the printed text. There is no message parameter, so this idiom is the usual way to add one.
  • <assert.h> can be included repeatedly. Each inclusion re-evaluates NDEBUG, so you can turn assertions on or off for part of a file. It is the one standard header without an include guard on purpose.
  • Commas. A comma outside parentheses splits macro arguments. Parenthesize: assert((compare(a, b) == 0)) is safest when the expression contains a compound literal or brace initializer. C99 and later accept the normal function-call case with no extra parentheses.
  • Release builds. -DNDEBUG (or -O2 -DNDEBUG in many build systems) removes every assertion, which makes them free, but also means untested release paths. Keep tests running on a build with assertions enabled.
  • static_assert checks a constant expression at compile time and fails the compile, not the run. In C23 it is a keyword and the message is optional (static_assert(sizeof(long) == 8);); in C11 and C17 you include <assert.h> and a message is required. It is unaffected by NDEBUG. See static_assert.
  • unreachable() from <stddef.h> (C23) is a different tool: it tells the compiler a point is never reached, and reaching it is undefined behavior, so do not use it as a checked assertion.
  • Abort leaves no cleanup. atexit handlers do not run and buffered stdout data can be lost, so flush output you want to see before a possible failure.