Headers: sharing an interface
Read a self-contained header, understand include guards, and separate shared declarations from program definitions.
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.
#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
#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
#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 contents | Reasoning |
|---|---|
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 helper | Gives 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
- WG14 N1570 — public C11 committee draft: 6.10.2, 6.2.2, 6.7.4, 6.9, 7.1.2. Stable core rules used for the C17 baseline; not the final ISO publication.
- GCC CPP: search paths
- GCC CPP: once-only headers
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.
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.
Read the explanation for every choice
- Including a header always links a library.
Header inclusion and supplying compiled definitions are separate build concerns.
- A header is a separate running program.
Headers supply source through inclusion; they do not run as independent programs.
- 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.
#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.