YOUR C LEARNING COMPANION

Find your next idea.

Learning path
Building programsChapter 41 of 73

Headers: sharing an interface

Read a self-contained header, understand include guards, and separate shared declarations from program definitions.

5 min readIntermediateC17 baseline
Offline reading
In this chapter8 sections

When several source files use one interface, they need matching declarations. A header shares those declarations. We will see what belongs in a header and why including a file does not create a separately linked library.

1. Share the description of an interface

A header commonly supplies function declarations, type definitions, macros, and selected inline helpers. A structure type definition describes a type; it does not by itself allocate a global structure object. A function prototype tells the compiler how to check a call; it does not by itself supply the function body or link the implementation.

The following three files form one small C17 program. The public contract is: a null point is not an origin, a non-null argument must point to a live readable struct CodedilePoint, and the function changes nothing. The header includes <stdbool.h> because its interface uses bool in C17.

C17 · project file · point.h
#ifndef CODEDILE_POINT_H
#define CODEDILE_POINT_H

#include <stdbool.h>

struct CodedilePoint { int x; int y; };
bool codedile_is_origin(const struct CodedilePoint *point);

#endif

2. A guard protects one preprocessing translation unit

The include guard defines a unique macro the first time the header is processed. Later inclusions in that same preprocessing translation unit skip the guarded contents. This also handles indirect paths, such as two headers including the same third header. Use a project-specific name, and keep the complete interface inside the guard.

A guard does not create one shared macro state across separately translated .c files. Each starts its own preprocessing context. It therefore cannot repair a header that accidentally defines an externally linked object in every source file. #pragma once is a widely supported alternative supplied by many implementations, but it is not a standard C directive with portable include-guard semantics.

3. Let the implementation include its own interface

C17 · project file · point.c
#include "point.h"
#include <stddef.h>

bool codedile_is_origin(const struct CodedilePoint *point)
{
    return point != NULL && point->x == 0 && point->y == 0;
}

Including its own header helps the compiler compare the function definition with the public declaration. The implementation includes <stddef.h> for its own use of NULL. A self-contained header provides what its declarations need instead of requiring callers to guess an include order. It need not include every header that the implementation happens to use.

4. Include the interface in each caller

C17 · project file · main.c
#include "point.h"
#include "point.h"
#include <assert.h>
#include <stddef.h>

int main(void)
{
    struct CodedilePoint start = { .x = 0, .y = 0 };
    assert(codedile_is_origin(&start));
    start.x = 1;
    assert(!codedile_is_origin(&start));
    assert(!codedile_is_origin(NULL));
    return 0;
}

The repeated include deliberately checks the guard. Both this source file and point.c see the same type and prototype; they are compiled separately and linked together. Normally include the header, rather than #include "point.c". Including an implementation file inserts its definitions into the current translation unit and can duplicate them if the build also compiles that implementation separately.

5. Know which definitions can be shared this way

Header contentsReasoning
extern int codedile_count;Declares an object whose one external definition belongs elsewhere.
int codedile_count = 0;Defines an external object; putting it in a broadly included header usually creates conflicting program definitions.
static const int codedile_limit = 10;Creates a separate internally linked object in each translation unit that uses the header.
static inline helperGives each translation unit its own internally linked function; call expansion is optional.

In C17, a file-scope object declaration without a storage-class specifier has external linkage; const alone does not change that. Thus const int limit = 10; in a shared header can still create conflicting external definitions. Plain inline is not a universal permission to repeat external definitions; C has specific inline/external-definition rules. Prefer a normal declaration plus one source definition, or a deliberately chosen static inline header helper.

For #include <...> and #include "...", the standard leaves search details to the implementation. GCC normally searches relative to the including file first for quoted includes, followed by configured paths; flags can change searches. A standard header need not be an ordinary physical file. Do not turn one tool’s folder conventions into a language guarantee.

Primary references and further reading

Before you move on

  • Headers share interface information needed during translation.
  • Guards can prevent repeated inclusion within a translation unit.
  • A header must be designed around declarations and any definitions permitted by the relevant linkage rules.
Keep these ideas separate
Include guard / One program-wide definition
A guard applies within preprocessing; it does not merge ordinary external definitions emitted by different translation units.
Explain it in your own words

What should a header include to remain usable when another source file includes it by itself?

Optional: say it aloud or keep a note. You can continue whenever you are ready.

Check your understanding

Optional. Answers are not saved or sent, and reading stays unrestricted.

Why place shared function declarations in a header?
Read the explanation for every choice
  1. Including a header always links a library.

    Header inclusion and supplying compiled definitions are separate build concerns.

  2. A header is a separate running program.

    Headers supply source through inclusion; they do not run as independent programs.

  3. To share a consistent interface across translation units.

    ✓ Correct reasoning. The declarations can be included where functions are used and where their definitions are checked.

C17

Quick reference from the earlier edition

Retained for existing section links and saved passages. The expanded explanation is above; documented corrections are recorded in the source review.

Headers share declarations, type definitions, macros, and interfaces. Put extern int count; in a header and one definition such as int count = 0; in a source file. In C, const alone does not give a file-scope object internal linkage: const int limit = 10; in a header can create multiple external definitions. static const objects give each translation unit its own object; static inline helpers are a common header pattern. Plain inline has additional external-definition rules and is not a blanket exception.

Include Guards

An include guard prevents a header's guarded contents from being processed repeatedly within one preprocessing translation unit, including indirect inclusion through other headers. It does not prevent external-definition conflicts between separately compiled source files at link time.

C17 · illustrative fragment
#ifndef MYHEADER_H
#define MYHEADER_H
/* declarations go here */
#endif

or the shorter, non-standard but nearly universally supported #pragma once.

System vs. User Headers

The C standard leaves header-search locations implementation-defined. With GCC, quoted includes normally search the directory of the including file first (not necessarily the shell's current working directory), then configured quote/include paths; angle-bracket includes use configured include paths. Compiler options can alter both searches. A standard header also need not exist as a physical .h file.

Overview of Standard Headers

Header Purpose
<stdio.h> Standard input/output
<stdlib.h> General utilities: memory management, conversions, process control
<string.h> String and raw-memory manipulation
<math.h> Floating-point mathematics
<ctype.h> Character classification and case conversion
<time.h> Date and time
<assert.h> Diagnostic assertions
<limits.h> Integer type size limits
<float.h> Floating-point type limits
<stddef.h> Common definitions (size_t, ptrdiff_t, NULL)
<stdbool.h> Boolean type and values (C99)
<stdint.h> Fixed-width integer types (C99)
<stdarg.h> Variadic function support
<setjmp.h> Non-local jumps
<signal.h> Signal handling
<locale.h> Locale-specific formatting
<errno.h> Error codes
<threads.h> Multithreading (C11, optional)
<stdatomic.h> Atomic operations (C11, optional)

Ready for the next idea?

Mark this chapter as read whenever you feel ready.

CHAPTER 41 / 73

In this chapter

Headers: sharing an interface

Search all 73 chapters in both languages.EN + HG

Try “pointer”, “why int”, or “undefined behavior”.

Concepts connect. Follow your curiosity.↑ ↓ to explore · Enter to open
MAKE YOURSELF COMFORTABLE

Your reading space

Appearance

A clear canvas with balanced contrast.

Text size

100%
AA

Reading tools

Your data stays in this browser

Export a backup before changing browsers or replacing an older version of the reader.

YOUR PERSONAL MARGINS

My notebook

Saved on this device
A LITTLE CLARITY

The glossary

A starting meaning, then a chapter to go deeper.

A QUICK DEFINITION

A little clarity

Read the full explanation →

A thought worth keeping