C Reference ยท Functions and Scope
Header files in C
Reference for C header files: what belongs in a header, include guards and pragma once, angle brackets versus quotes, forward declarations and include order.
A header file is a text file, usually ending in .h, that you paste into a source file with #include. It holds the declarations other files need to use a module: function prototypes, type definitions, constants and macros. The matching .c file holds the definitions.
The preprocessor does the pasting before compilation, so a header is nothing special to the compiler. That is why headers need discipline: including the same header twice would repeat its declarations, and a definition placed in a header would be duplicated in every file that includes it.
#ifndef STACK_H #define STACK_H /* declarations here */ #endif
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.
Syntax
#include <name.h> /* system headers: search the compiler's include path */ #include "name.h" /* your headers: search the current file's directory first */ #ifndef NAME_H /* include guard */ #define NAME_H ... #endif #pragma once /* widely supported, not standard */
| Item | Description |
|---|---|
#include <h> |
Searches implementation-defined places, usually the system include directories (and paths given with -I). |
#include "h" |
Searches implementation-defined places first (typically the directory of the including file), then falls back to the <> search. |
| include guard | #ifndef/#define/#endif around the contents, with a macro name unique to the header, so repeated inclusion is harmless. |
__has_include |
C23 preprocessor test for whether a header exists. |
Errors / undefined behavior: defining an external function or variable in a header and including it in two files gives linker errors (multiple definitions). Two headers using the same guard macro silently drop the second. Circular includes without guards fail to compile. Defining or redefining a reserved identifier or a standard library name in a header is undefined.
Usage notes
- Declare in the header, define in the source file. Put prototypes,
externvariable declarations, types,enums, macros andstatic inlinefunctions in headers. Put function bodies and variable definitions in.cfiles. - Guard every header. Use a name derived from the path (
PROJECT_STACK_H).#pragma onceis shorter and supported by all major compilers, but it is not in the C standard. - Self-contained headers. A header should compile when included first in an empty file. Include what it needs (
<stddef.h>forsize_t) and test this by including it first in its own.cfile. - Include only what you use. Extra includes slow builds and create hidden dependencies. Prefer a forward declaration (
struct node;) when you only use pointers to a type. - Include order. A common order is: the module's own header, then project headers, then standard headers. Putting the own header first proves it is self-contained.
- No
using-style pollution. C has no namespaces, so every name in a header is visible to every includer. Prefix public names with a module name. - Don't include
.cfiles. It duplicates definitions and breaks separate compilation. - Document the contract (ownership, error values, thread safety) next to each declaration, because the header is the module's public interface. Keep private details out; see Opaque types.
- Dependency tools. Build systems track header dependencies with
-MMD. Without that, editing a header may not rebuild the files that include it. - C23
#embedpastes the bytes of a file as an initializer; it complements#includefor data.