C Header Files — Declaration, Inclusion, and Organization

In this tutorial, you will learn about C Header Files. We cover key concepts, practical examples, and best practices to help you master this topic.

C header files (.h) contain declarations of functions, types, macros, and external variables that are shared across multiple source files, with include guards preventing duplicate definitions and the extern keyword enabling cross-file variable access.

What You Will Learn

• Writing header files for function declarations
• Using include guards (#ifndef / #define / #endif)
• Declaring external variables with extern
• Forward declaring structures and functions
• Splitting large projects into modular headers
• Circular dependency resolution

Why It Matters

Without headers, every source file would need to duplicate declarations for every function it calls from another file. Headers provide a single source of truth for interfaces. When a function signature changes, you update the header and the compiler catches all callers that need updating. Durga Antivirus Pro uses a layered header architecture: base types in common.h, OS abstractions in platform.h, scan engine in scanner.h, and UI in interface.h.

Real-World Use

A team of 10 developers works on a video game engine. Each subsystem (rendering, physics, audio, input) has its own header file. The physics developer changes a function signature, recompiles the physics header, and the build system recompiles all files that include it, revealing every call site that needs updating.

Learning Path

flowchart LR
  A[Preprocessor] --> B[Header Files\nYou are here]
  B --> C[Makefiles]
  style B fill:#f90,color:#fff

Basic Header Structure

// math_utils.h
#ifndef MATH_UTILS_H
#define MATH_UTILS_H

int add(int a, int b);
int subtract(int a, int b);
double power(double base, int exp);

#endif  // MATH_UTILS_H

// math_utils.c
#include "math_utils.h"

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

double power(double base, int exp) {
    double result = 1.0;
    for (int i = 0; i < exp; i++) {
        result *= base;
    }
    return result;
}

// main.c
#include <stdio.h>
#include "math_utils.h"

int main() {
    printf("10 + 5 = %d\n", add(10, 5));
    printf("2^10 = %.0f\n", power(2.0, 10));
    return 0;
}

Extern Variables

// config.h
#ifndef CONFIG_H
#define CONFIG_H

// Declare external variables
extern int log_level;
extern char log_file[256];

int init_logging(void);

#endif

// config.c
#include "config.h"
#include <string.h>

// Define the variables (once)
int log_level = 2;
char log_file[256] = "app.log";

int init_logging(void) {
    // Open log file for writing
    return 0;
}

// main.c
#include <stdio.h>
#include "config.h"

int main() {
    init_logging();
    printf("Log level: %d\n", log_level);
    printf("Log file: %s\n", log_file);
    return 0;
}

If you forget extern in the header, each .c file that includes it gets its own definition, causing linker errors.

Forward Declarations

Forward declarations break circular dependencies between types:

// player.h
#ifndef PLAYER_H
#define PLAYER_H

// Forward declare struct team
struct team;

typedef struct {
    int id;
    char name[64];
    struct team *current_team;  // Uses forward declaration
} Player;

void player_print_team(const Player *p);

#endif

// team.h
#ifndef TEAM_H
#define TEAM_H

#include "player.h"

typedef struct {
    int id;
    char name[64];
    Player members[11];
    int member_count;
} Team;

#endif

Type Definitions in Headers

// types.h
#ifndef TYPES_H
#define TYPES_H

#include <stdint.h>
#include <stdbool.h>

// Fixed-width integers
typedef uint8_t u8;
typedef uint32_t u32;
typedef uint64_t u64;

// Common structures
typedef struct {
    float x, y, z;
} Vector3;

typedef struct {
    Vector3 position;
    Vector3 velocity;
    float mass;
} PhysicsBody;

// Function pointer type
typedef int (*Comparator)(const void *, const void *);

#endif

Header Dependency Chains

// base.h
#ifndef BASE_H
#define BASE_H
typedef unsigned long ulong;
#endif

// geometry.h
#ifndef GEOMETRY_H
#define GEOMETRY_H
#include "base.h"
typedef struct { ulong width, height; } Rect;
#endif

// renderer.h
#ifndef RENDERER_H
#define RENDERER_H
#include "geometry.h"
void draw_rect(Rect r);
#endif

// main.c
#include "renderer.h"  // Indirectly includes geometry.h and base.h
int main() {
    Rect r = {800, 600};
    draw_rect(r);
    return 0;
}

Static Functions in Headers

Functions declared static inline in headers can be defined in the header without causing multiple-definition errors:

// utils.h
#ifndef UTILS_H
#define UTILS_H

static inline int clamp(int val, int min, int max) {
    if (val < min) return min;
    if (val > max) return max;
    return val;
}

static inline int max3(int a, int b, int c) {
    int ab = (a > b) ? a : b;
    return (ab > c) ? ab : c;
}

#endif

Common Mistakes

1. Missing include guards: Without guards, a header that is #included twice (directly or indirectly) causes duplicate type and function declaration errors. Always use #ifndef / #define / #endif.

2. Defining variables in headers: int counter = 0; in a header creates a separate definition in every .c file that includes it, causing linker errors. Use extern in the header and define it in exactly one .c file.

3. Circular includes: A.h includes B.h and B.h includes A.h. The preprocessor enters an infinite loop or one header is processed before the other's types are defined. Use forward declarations to break the cycle.

4. Not including what you use: Relying on transitive includes from other headers makes your code fragile. If those headers change their includes, your code breaks. Always include the headers your file directly needs.

5. Inconsistent declarations: If the declaration in the header differs from the definition in the .c file, the compiler detects it only if the header is included in both. Always include the header in its own .c file to get compiler checking.

Practice Questions

1. Why must include guards start before any code and end after the last declaration?
2. What problem does extern solve, and why can't you just put the variable definition in the header?
3. How do forward declarations resolve circular dependencies between two headers?
4. What is the difference between #include "math.h" and putting the function declarations directly in the .c file?
5. Challenge: Design a header hierarchy for a small game engine with modules: math (vectors, matrices), entity (game objects, components), physics (collision detection), rendering (graphics), and audio (sound playback). Each module gets its own header. Ensure no circular dependencies. Implement forward declarations where needed.

Mini Project

Build a modular data structures library:

• vector.h / vector.c: Dynamic array (push, pop, get, set, resize)
• list.h / list.c: Singly Linked List (insert, remove, find, iterate)
• hashmap.h / hashmap.c: Hash Table (put, get, delete, contains)
• dsa.h: Umbrella header that includes all three
• Each header has complete include guards
• Each type uses opaque struct pointers (forward declared in header, defined in .c)
• Write a test program that uses all three data structures
• No circular dependencies between headers

FAQ

What is Next

Proceed to Makefiles to automate the compilation of multi-file projects. Then explore Multiple Files for managing large codebases.