⚙️ 15. Preprocessor & Header Files

Before the C compiler translates your program into machine code, another stage can process special instructions called preprocessing directives.

These directives begin with the character #.

#include <stdio.h>
#define MAX 100

These directives affect the source before the resulting C statements are compiled. They are not instructions that run each time the program executes.

15.1 What Is the C Preprocessor?

The preprocessor handles directives and macro expansion before the compiler translates the resulting C code. For example, it can replace a symbolic limit with its defined value.

Common directives include:

• #include
• #define
• #undef
• #if
• #ifdef
• #ifndef
• #elif
• #else
• #endif
• #error
• #line
• #pragma

15.2 Where Does the Preprocessor Fit?

 C Source File │ ▼ Preprocessing │ ▼ Translation / Compilation │ ▼ Object Code │ ▼ Linking │ ▼ Executable Program 

For learning purposes, it is useful to think of preprocessing as the stage that handles directives such as #include and #define before the compiler translates the resulting source.

15.3 Preprocessor Directive Basics

A directive normally begins with #.

#define VALUE 10

The directive is recognized by the preprocessing stage.

Unlike an ordinary C statement, it does not require a semicolon at the end.

#include <stdio.h>
#define MAX 100

15.4 #include

The #include directive brings the named header’s contents into the source being processed. The header can supply the declarations needed by the code that follows.

#include <stdio.h>

This is why a program can use declarations associated with standard input/output facilities such as printf and scanf.

15.5 <...> vs "..."

Two common forms are:

#include <stdio.h>
#include "myheader.h"

Angle brackets are normally used for standard or library headers, while quotes are normally used for project headers. The compiler’s documented search paths determine where each form looks.

15.6 What Is a Header File?

A header file commonly contains declarations, type definitions, macros and other information intended to be shared by multiple source files.

Examples from the C standard library include:

• stdio.h — input/output facilities
• stdlib.h — general utilities
• string.h — string handling
• math.h — mathematics functions
• ctype.h — character classification
• time.h — date and time facilities
• limits.h — integer limits
• float.h — floating-point characteristics

15.7 #define

The #define directive defines a macro.

#define MAX_MARKS 100

When an eligible macro name appears later, its replacement tokens are inserted. Macro names inside string literals are not replaced as ordinary identifiers.

#include <stdio.h>

#define MAX_MARKS 100

int main(void)
{
    printf("%d\n", MAX_MARKS);
    return 0;
}

Conceptually, the preprocessor produces source equivalent to:

printf("%d\n", 100);

15.8 Object-Like Macros

A macro without parameters is commonly called an object-like macro.

#define PI 3.14159265358979323846
#define MAX_SIZE 100
#define COMPANY_NAME "CodeBhavya"

These macros replace the identifier with their replacement token sequence.

15.9 Function-Like Macros

A function-like macro has parameters.

#define SQUARE(x) ((x) * (x))

Example:

int result = SQUARE(5);

Conceptually becomes:

int result = ((5) * (5));

15.10 Why Macro Parentheses Matter

Consider this unsafe macro:

#define SQUARE(x) x * x

Now:

SQUARE(2 + 3)

can become:

2 + 3 * 2 + 3

which is not the intended mathematical grouping.

Prefer:

#define SQUARE(x) ((x) * (x))

 Macro │ ▼ Token substitution │ ▼ Operator precedence still applies │ ▼ Parentheses protect the intended expression 

15.11 Macro Side Effects

Parentheses protect grouping, but a macro can still use an argument twice. Be careful with an argument that changes a variable, such as i++.

#define SQUARE(x) ((x) * (x))

Consider:

int i = 3; int result = SQUARE(i++);

The macro expansion contains two occurrences of i++. In this multiplication, the changes to i are unsequenced, so the expression has undefined behavior. Do not run it and treat one compiler’s output as a valid answer.

15.12 Macro vs Function

15.13 #undef

The #undef directive removes a macro definition.

#define LIMIT 100
#undef LIMIT

After #undef, the macro name is no longer defined by that macro definition.

15.14 Conditional Compilation

Conditional compilation chooses source code before the program runs. This differs from an if statement, which chooses a path while the compiled program is running.

#if CONDITION
/* selected source */
#endif

If the condition evaluates to nonzero after preprocessing, the controlled section is included.

Example

#define DEBUG 1
#if DEBUG
printf("Debug mode\n");
#endif

Because DEBUG expands to 1, the controlled section is included.

15.15 #if, #elif and #else

#define LEVEL 2
#if LEVEL == 1
/* beginner */
#elif LEVEL == 2
/* intermediate */
#else
/* other */
#endif

The preprocessor selects one appropriate branch.

 #if │ ├── condition true │ ↓ │ include branch │ └── condition false ↓ #elif? │ ├── true → include branch │ └── false → continue ↓ #else 

15.16 #ifdef

#ifdef tests whether a macro is defined.

#define DEBUG
#ifdef DEBUG
printf("Debugging enabled\n");
#endif

The value of the macro is not the point here. The test asks whether the macro name is defined.

15.17 #ifndef

#ifndef tests whether a macro is not defined.

#ifndef MAX_SIZE
#define MAX_SIZE 100
#endif

This pattern is especially important for protecting header files from repeated inclusion.

15.18 Header Include Guards

If two headers both include the same project header, its definitions could be seen twice. A guard macro makes the second inclusion skip the guarded contents within that translation unit.

#ifndef STUDENT_H
#define STUDENT_H
struct Student { int id; int marks; };
void displayStudent(struct Student s);
#endif

 First inclusion │ ▼ STUDENT_H not defined │ ▼ Define STUDENT_H │ ▼ Process header contents Second inclusion │ ▼ STUDENT_H already defined │ ▼ Skip contents 

15.19 How Project Header Files Work

A larger C project can separate declarations and implementations.

student.h

#ifndef STUDENT_H
#define STUDENT_H

struct Student {
    int id;
    int marks;
};

void displayStudent(struct Student s);

#endif

student.c

#include <stdio.h>
#include "student.h"

void displayStudent(struct Student s)
{
    printf("ID = %d\n", s.id);
    printf("Marks = %d\n", s.marks);
}

main.c

#include "student.h"

int main(void)
{
    struct Student s = {101, 90};
    displayStudent(s);
    return 0;
}

15.20 Predefined Macros

C implementations provide several predefined macros. Common examples include:

__FILE__ __LINE__ __DATE__ __TIME__ __STDC__ __STDC_VERSION__

Their meanings are useful for diagnostics and implementation/language-version information, although availability and exact predefined macro set can depend on the language standard and implementation.

Example

#include <stdio.h>

int main(void)
{
    printf("File: %s\n", __FILE__);
    printf("Line: %d\n", __LINE__);
    return 0;
}

__FILE__ identifies the source file and __LINE__ identifies the current source line in the preprocessing context.

15.21 __STDC_VERSION__

When provided by a conforming implementation for the applicable standard mode, __STDC_VERSION__ can be used to identify the C language standard version.

#include <stdio.h>

int main(void)
{
#ifdef __STDC_VERSION__
    printf("C standard version: %ld\n", (long)__STDC_VERSION__);
#else
    printf("C standard version macro not available\n");
#endif
    return 0;
}

15.22 #error

The #error directive requests a diagnostic containing the specified preprocessing tokens.

#ifndef REQUIRED_FEATURE
#error "Required feature is not enabled"
#endif

Use it for an unsupported configuration so the compiler reports the problem during translation, before a program is run.

15.23 #pragma

#pragma provides implementation-defined instructions to the compiler.

#pragma

The actual effect depends on the compiler and platform.

15.24 #line

The #line directive changes the logical line number and optionally the filename used in later diagnostics and predefined macros. It does not move execution to another line.

#line 100 "generated.c"

This is primarily useful in generated source and specialized tooling.

15.25 Program Tracing: Macro Replacement

#define BONUS 10

int main(void)
{
    int marks = 80;
    marks = marks + BONUS;
    return 0;
}

 Original source marks = marks + BONUS; │ ▼ Macro replacement │ ▼ marks = marks + 10; │ ▼ Compiler processes resulting source 

The macro does not create a runtime variable called BONUS.

15.26 Program Tracing: Conditional Compilation

#define MODE 2
#if MODE == 1
printf("Basic");
#elif MODE == 2
printf("Advanced");
#else
printf("Unknown");
#endif

 MODE │ ▼ 2 │ ▼ #if MODE == 1 │ └── false #elif MODE == 2 │ └── true │ ▼ printf("Advanced"); #else Skipped 

The non-selected source branches are excluded from the resulting translation unit.

15.27 Program Tracing: Include Guard

#ifndef CONFIG_H
#define CONFIG_H
#define MAX_USERS 100
#endif

 Include config.h │ ▼ Is CONFIG_H defined? │ ┌───┴────┐ │ │ No Yes │ │ ▼ ▼ Define Skip CONFIG_H contents │ ▼ Process header 

15.28 Macro Stringification — Preview

Function-like macros can use # in a replacement list to convert a macro argument into a string literal.

#define SHOW_NAME(x) #x

For example:

SHOW_NAME(CodeBhavya)

produces a string-literal representation equivalent to:

"CodeBhavya"

15.29 Token Pasting ## — Preview

The ## operator in a macro replacement list combines preprocessing tokens.

#define JOIN(a, b) a##b

For example:

JOIN(total, 1)

can form the preprocessing token:

total1

15.30 Common Mistakes

#define MAX 100;

#define MAX 100

#define SQUARE(x) x * x

#define SQUARE(x) ((x) * (x))

15.31 Common Confusions

15.32 Complete Program: Macro + Conditional Compilation

#include <stdio.h>

#define PASS_MARKS 40
#define DEBUG

int main(void)
{
    int marks = 75;
#ifdef DEBUG
    printf("Checking marks...\n");
#endif
    if (marks >= PASS_MARKS) {
        printf("Pass\n");
    } else {
        printf("Fail\n");
    }
    return 0;
}

Trace

1. stdio.h is included.
2. PASS_MARKS is defined as 40.
3. DEBUG is defined.
4. The #ifdef DEBUG block is included.
5. PASS_MARKS is replaced by its macro replacement.
6. The resulting C source is compiled normally.

15.33 Good Header File Design

A useful project header should expose information that other source files need.

For example:

#ifndef CALCULATOR_H
#define CALCULATOR_H
int add(int a, int b);
int subtract(int a, int b);
#endif

The implementation can remain in a source file:

#include "calculator.h"

int add(int a, int b)
{
    return a + b;
}

int subtract(int a, int b)
{
    return a - b;
}

15.34 Placement-Important Macro Patterns

#define MAX(a, b) ((a) > (b) ? (a) : (b))

This demonstrates parentheses around both parameters and the complete replacement expression.

However, repeated evaluation is still possible:

MAX(i++, j++)

Therefore macros should be designed carefully.