C preprocessor

What it is and why it exists

The C preprocessor reads source files and handles preprocessing directives introduced by # before normal compilation. #include brings in file contents, #if selects tokens to keep, and #define creates a macro . The preprocessor doesn’t understand C object types, scopes, or runtime values.

Preprocessing solves composition and configuration problems that exist before compilation. Public declarations can live in headers, platform adapters can select an implementation at build time, and macros can generate repeated token patterns. You’ll meet it in public library headers, -D definitions from build systems, logging and assertion wrappers, and platform-detection code.

“Text substitution” is a useful approximation, but it isn’t precise enough. Macros operate on preprocessing tokens: they don’t replace characters inside string literals, and they can’t freely join half of one token to half of another. The # and ## operators have specific stringification and token-pasting rules.

Preprocessor output still isn’t an executable program. After includes and macro replacement, one .c file forms a translation unit . Only then does the compiler analyze declarations, types, and expressions before assembly and linking. gcc -E lets you inspect this boundary.

How it works

This flow shows only the boundaries needed for everyday code. The standard specifies several translation phases; an implementation may combine them as long as the result follows the required behavior.

Before directives are handled

A backslash immediately followed by a newline joins two physical lines into one logical line. Source characters are then recognized as preprocessing tokens and whitespace, with each comment replaced by one space during that process. Nothing can trail a multiline macro’s backslash if it would stop that splice from occurring.

The # in a preprocessing directive must be the first preprocessing token on a logical line, although whitespace may precede it. Directives control preprocessing only; indenting #if inside a normal C block doesn’t make it a runtime if. A group excluded by conditionals never reaches the later compilation stage.

#include makes the implementation locate a named file and continue processing it as input at that point. Quoted and angle-bracket forms use different implementation-defined search sequences. Exact directories come from compiler defaults and options such as -I, so punctuation alone doesn’t reveal the full path on every toolchain.

Object-like and function-like macros

An object-like macro replaces its name with its replacement list. A function-like macro expands only when its name is followed by an invocation parenthesis; its parameters receive argument token sequences, not values that already have C types.

Ordinary parameters are macro-expanded before substitution into the replacement list. A parameter next to # or ## isn’t expanded first on that pass, which is why stringifying an expanded value usually needs an indirection macro. The replacement is rescanned afterward, allowing newly exposed macro names to expand.

A macro currently being expanded is temporarily unavailable for replacement at the corresponding points in that scan. This prevents direct or indirect self-reference from recursing forever, but the leftover macro name will usually make invalid C code. Macro recursion isn’t a general looping facility.

Conditionals and definition state

#ifdef NAME asks only whether the name is defined; it doesn’t care whether its replacement list is 0. #if NAME expands its expression first, and remaining ordinary identifiers take the value zero in the preprocessing constant expression. Combine defined(NAME) with a numeric check when “not supplied” and “explicitly disabled” must differ.

Build systems commonly provide definitions with -DNAME=value, while a header supplies a default with #ifndef NAME. Configuration needs one clear owner. If command-line options, a generated header, and an ordinary header define the same macro independently, the result can depend on include order and may produce a redefinition diagnostic.

#error fails the current preprocessing operation, which suits unsupported or contradictory configurations. C23 also standardizes #warning, but a warning shouldn’t enforce a condition that must stop the build. Use #error or a compilation-stage static assertion for mandatory constraints.

Predefined names and macro lifetime

The implementation supplies a set of standard predefined macros before it processes user source. They suit source-location reporting and checks on the language environment, but they don’t replace product configuration owned by a build system. __func__ is a predefined identifier inside a function body, not a preprocessing macro.

When checking a version, first use defined(__STDC_VERSION__) to handle modes without that macro, then compare the required version number. Compiler identity macros only describe the current implementation. Treating __GNUC__ as sufficient proof of one feature can misclassify compatible compilers or other versions.

#undef NAME ends later macro replacement for that name. It can retire a local helper or permit controlled reconfiguration. Defining the same name again with a different replacement list while it remains defined normally requires a diagnostic; relying on the result turns include order into a hidden input.

The standard reserves several classes of identifiers for implementations, especially file-scope names beginning with an underscore and double-underscore forms. Project code should use an explicit prefix instead of copying the naming style of predefined macros.

Include guards

A header can arrive in one translation unit along several include paths. An include guard wraps its contents in a unique macro so later inclusions see the definition and skip the body.

#ifndef ACME_NET_PACKET_H
#define ACME_NET_PACKET_H

struct packet;
int packet_size(const struct packet *value);

#endif

The guard name must be unique across the project. If two unrelated headers happen to use the same guard, whichever is included first silently hides the other. #pragma once is supported by mainstream toolchains, but it isn’t a directive in the C23 language standard.

An include guard only prevents the same header body from being processed repeatedly in one translation unit. It doesn’t resolve mutual dependencies on complete types, and it doesn’t make an ordinary external definition in a header unique across the program. Break dependencies with forward declarations and put definitions that need one storage instance in a source file.

Examples

These four programs cover indirect stringification, statement macros, build switches, and X macros in that order. I compiled every file with GCC 13.3.0 using -std=c2x -Wall -Wextra -Wconversion -Wpedantic -Werror; the displayed text is the actual output.

Expand, then stringify

Writing STRINGIFY_RAW(API_MAJOR) directly produces "API_MAJOR" because # suppresses prescan for that parameter. The outer STRINGIFY expands the argument first, then passes the result to the inner macro that performs stringification.

The compiler concatenates adjacent string literals, so API_VERSION becomes one string. The two macro layers aren’t decoration: removing the outer one changes the observable result.

This pattern also puts build definitions into diagnostic text. If a numeric value is needed in a C expression, keep using API_MAJOR itself instead of parsing the stringified form back into a number.

Wrap statements and optional arguments

The statement macro uses do { ... } while (0), so its call site can supply one semicolon like an ordinary statement. C23’s __VA_OPT__ inserts the comma only when the variadic arguments are nonempty.

#include <stdio.h>

#define AUDIT(format, ...)                                      \
    do {                                                        \
        printf("[audit] " format __VA_OPT__(,) __VA_ARGS__);   \
        putchar('\n');                                         \
    } while (0)

static void record_login(int accepted) {
    if (accepted)
        AUDIT("login accepted");
    else
        AUDIT("login rejected for user %d", 17);
}

int main(void) {
    record_login(1);
    record_login(0);
    return 0;
}

[audit] login accepted
[audit] login rejected for user 17

The outer wrapper turns the expansion into one statement and prevents the caller’s else from binding to an if inside the macro. The definition doesn’t end with a semicolon; that punctuation belongs to the call syntax.

This macro still provides no format type safety by itself. A compiler may diagnose mismatches using its knowledge of printf, but the macro doesn’t validate the format string and arguments. Put richer logging policy in a function, leaving only source locations or conditional removal in a thin macro layer.

Select an implementation with a build definition

This file represents feature state with a numeric macro and rejects values other than zero and one. The output below comes from a build that also passes -DENABLE_METRICS=1.

#include <stdio.h>

#ifndef ENABLE_METRICS
#define ENABLE_METRICS 0
#endif

#if ENABLE_METRICS != 0 && ENABLE_METRICS != 1
#error "ENABLE_METRICS must be 0 or 1"
#endif

#if ENABLE_METRICS
static void record_metric(const char *name, int value) {
    printf("metric %s=%d\n", name, value);
}
#else
#define record_metric(name, value) ((void)0)
#endif

int main(void) {
    record_metric("requests", 3);
    printf("metrics: %s\n", ENABLE_METRICS ? "enabled" : "disabled");
    return 0;
}

metric requests=3
metrics: enabled

Changing the condition to #ifdef ENABLE_METRICS would also select the enabled branch when the default definition is zero. Use #if ENABLE_METRICS for a numeric switch; reserve #ifdef for flags whose presence is the whole meaning.

The disabled branch replaces the call with ((void)0), so it doesn’t evaluate name or value. If an argument has a side effect, enabled and disabled builds behave differently at runtime. Calling code shouldn’t depend on side effects in logging or metrics arguments.

Generate consistent declarations from one list

An X macro separates a data list from the action used on each traversal. The same status table generates enum members and switch arms here, avoiding two manually maintained lists that can drift apart.

#include <stdio.h>

#define STATUS_LIST(X)  \
    X(PENDING, 10)      \
    X(RUNNING, 20)      \
    X(COMPLETE, 30)

#define DECLARE_STATUS(name, code) STATUS_##name = code,
enum status {
    STATUS_LIST(DECLARE_STATUS)
};
#undef DECLARE_STATUS

static const char *status_name(int value) {
    switch (value) {
#define STATUS_CASE(name, code) case STATUS_##name: return #name;
        STATUS_LIST(STATUS_CASE)
#undef STATUS_CASE
    default:
        return "UNKNOWN";
    }
}

int main(void) {
    printf("%d %s\n", STATUS_RUNNING, status_name(STATUS_RUNNING));
    printf("%d %s\n", 99, status_name(99));
    return 0;
}

20 RUNNING
99 UNKNOWN

Undefining each action macro after use limits how long it can affect later source. STATUS_LIST can remain as the public generation entry point, but its line format and argument count now form an interface that must be maintained.

This technique fits a small, stable declaration table. If the list needs conditionals, nested data, or consumption by external tools, one YAML or JSON input and a generator is usually easier to verify. Don’t stretch the preprocessor into a data language.

Pitfalls

Treating parentheses as a single-evaluation guarantee

Fix: prefer a static inline function for value computation, which evaluates each argument once before the call. If a macro truly must accept several types, document the “no side effects in arguments” contract and enforce its call sites with diagnostics and tests.

Reading a numeric switch with #ifdef

Fix: use #if FEATURE_X for a zero-or-one switch and supply its default with #ifndef. When an omitted state must remain distinct, first check defined(FEATURE_X), then validate the permitted numeric values separately.

Letting a statement macro leak control flow

Fix: wrap a statement macro in do { ... } while (0) and omit the final semicolon from its definition. Caller code should still brace if and else; any return, break, or continue hidden inside the macro must remain conspicuous and documented.

Colliding macro and guard names

Fix: prefix public macros with the project and component, derive guards from a stable project path, and #undef temporary helpers immediately after use. Don’t define implementation-reserved identifiers or leak generic names from public headers.

Depending on compiler extensions by default

Fix: start with functions, __VA_OPT__, and ordinary directives supplied by the target standard. When an extension is necessary, isolate it in an adapter header, guard it by compiler and version, and make CI build every toolchain the project promises to support.

Further reading

Start with the C23 working draft for preprocessing directives and replacement rules, then use the GCC manuals for local options and extensions. cppreference is useful for quick syntax lookup, but the draft and compiler documentation decide the final answer.

• WG14 N3096: C23 working draft
• GCC 13.3: The C preprocessor
• GCC 13.3: Preprocessor options
• cppreference: C preprocessor