The C and C++ header file (.h, .hpp)

The basics

What is an H file?

Anatomy

What's inside a header file

A header says what exists without, for the most part, saying how it works: types, function prototypes, constants and the occasional small inline function. Here is a typical C header that is also safe to use from C++, part by part.

/* geometry.h: points and the functions that measure them */
#ifndef GEOMETRY_H
#define GEOMETRY_H

#include <stddef.h>

#ifdef __cplusplus
extern "C" {
#endif

#define GEOMETRY_PI 3.14159265358979323846

typedef struct {
    double x, y;
} point;

double distance(point a, point b);
double polygon_area(const point *corners, size_t count);

extern int geometry_calls;

static inline double square(double v)
{
    return v * v;
}

#ifdef __cplusplus
}
#endif

#endif /* GEOMETRY_H */

1. 1/* geometry.h: … */

   A comment

   Often the documentation for the whole library: the header is the part users read.

2. 2#ifndef GEOMETRY_H / #define GEOMETRY_H

   The include guard

   The first time the header is included, GEOMETRY_H isn't defined, so the contents are read and the macro is defined. Any later include in the same file skips straight to the final #endif.

3. 3#include <stddef.h>

   What the header itself needs

   size_t is used below, so the header includes the header that defines it. A good header compiles on its own, whatever was included before it.

4. 4#ifdef __cplusplus / extern "C" {

   C linkage for C++

   C++ compilers encode parameter types into function names (name mangling); C compilers don't. extern "C" makes C++ code look for the plain C names, so it can link to the compiled C library. __cplusplus is only defined by C++ compilers, so C never sees it.

5. 5#define GEOMETRY_PI …

   A macro constant

   Prefixed with the library's name, because macros ignore scopes and namespaces and can collide with anyone else's.

6. 6typedef struct { double x, y; } point;

   A type definition

   Every file that uses point needs to know its layout, so the definition goes in the header. Type definitions are allowed to repeat across files; a function or variable definition isn't.

7. 7double distance(point a, point b);

   Function declarations

   A prototype: name, parameters and return type, ending in a semicolon instead of a body. The body lives in geometry.c, compiled once.

8. 8extern int geometry_calls;

   A variable declaration

   extern says the variable is defined somewhere else, in exactly one .c file. Without extern, every file that includes the header would define its own.

9. 9static inline double square(double v) { … }

   An inline function

   Small functions can be defined in a header if they're static inline (C) or inline (C++). Each including file gets a copy the compiler can inline, with no clash at link time.

10. 10#endif /* GEOMETRY_H */

    The end of the guard

    Closes the #ifndef. The comment is a habit that makes long headers easier to read.

Under the hood

How #include works: declarations here, definitions there

/* geometry.c: the definitions */
#include <math.h>
#include "geometry.h"

int geometry_calls = 0;

double distance(point a, point b)
{
    geometry_calls++;
    return sqrt(square(b.x - a.x) + square(b.y - a.y));
}
/* … polygon_area … */

/* main.c: a user of the header */
#include <stdio.h>
#include "geometry.h"

int main(void)
{
    point a = {0, 0}, b = {3, 4};
    printf("%g\n", distance(a, b));   /* prints 5 */
    return 0;
}

/* the build: */
/*   cc -c geometry.c                    -> geometry.o, the code      */
/*   cc -c main.c                        -> main.o, calls distance()  */
/*   cc main.o geometry.o -lm -o demo    -> the linker joins them     */

Conventions

Include guards vs #pragma once

/* Include guard: standard C and C++, works everywhere */
#ifndef MYLIB_PARSER_H
#define MYLIB_PARSER_H
/* … declarations … */
#endif /* MYLIB_PARSER_H */

/* #pragma once: one line, not in the standard, supported by
   GCC, Clang and MSVC */
#pragma once
/* … declarations … */

Related formats

.h vs .hpp, and other header extensions

Packaging

Header-only libraries

Troubleshooting

Header errors people hit most, and what they mean

How to

How to open, read and edit a header file

Free downloads

Sample header files to download

Free sample header files, with the source files that use them, for testing compilers, IDEs, syntax highlighting and code viewers. They build with GCC and Clang, as C and as C++, with warnings on and none reported. Download all five into one folder to build them.

Loading…

What's inside sample-header.h

The header is commented: open it in a text editor and each numbered comment marks one of these parts. Its comments also give the build commands that connect it to the other samples.

1. Comment 1: the include guard

   #ifndef SAMPLE_HEADER_H / #define SAMPLE_HEADER_H. sample-main.c includes the header twice on purpose to show the guard working.

2. Comment 2: the header's own includes

   stdbool.h and stddef.h, for bool and size_t, so the header compiles whatever was included before it.

3. Comments 3 and 9: extern "C"

   Opened and closed inside #ifdef __cplusplus, so the C functions link from sample-main.cpp. The build check for these samples confirms that removing it makes the C++ link fail.

4. Comments 4 and 5: macros and a type

   A version string, a size limit, and a stats_t struct that callers can create as an ordinary local variable.

5. Comment 6: function declarations

   Five prototypes ending in semicolons. Their bodies are in sample-header.c.

6. Comment 7: an extern variable

   extern const char stats_library_name[];, defined once in sample-header.c.

7. Comments 8 and 10: an inline function and the end of the guard

   A static inline function, one of the few function definitions that belongs in a C header, then the closing #endif.

All sample H files

• Commented C header with an include guard

  sample-header.h · 2.6 KB (2,627 bytes)

  The header of a tiny statistics library: an include guard, its own includes, extern "C" for C++, macros, a struct, prototypes, an extern variable and a static inline function, with numbered comments explaining each part.

  • Checking syntax highlighters and IDEs on headers
  • Teaching what belongs in a header
  DownloadOpen

• The matching source file

  sample-header.c · 1.5 KB (1,531 bytes)

  The definitions behind sample-header.h: it includes its own header first, defines the extern variable once and implements the five functions.

  • Showing how a header and its source file pair up
  • Building the C and C++ examples
  DownloadOpen

• C program that uses the header

  sample-main.c · 950 bytes

  Includes the header twice to show the guard working, then calls the library. Build: cc -std=c17 sample-main.c sample-header.c -o stats-c.

  • A two-file C build test
  • Include-guard demonstration
  DownloadOpen

• C++ program that uses both headers

  sample-main.cpp · 1.3 KB (1,331 bytes)

  Calls the C library through its extern "C" header, linked against sample-header.o compiled by a C compiler, and uses the header-only C++ library to draw a text bar chart.

  • Testing mixed C and C++ builds
  • Checking that `extern "C"` linkage works with your toolchain
  DownloadOpen

• Header-only C++ library (#pragma once)

  sample-header-only.hpp · 1.5 KB (1,545 bytes)

  A .hpp header guarded with #pragma once, containing a function template, an inline function and an inline constexpr variable: everything a header-only library needs, with comments on why each is allowed in a header.

  • Comparing `#pragma once` with include guards
  • Testing tools that treat `.hpp` differently from `.h`
  DownloadOpen

Ways to test with them

• Mixed C and C++ builds: compile sample-header.c with a C compiler and link it into sample-main.cpp with a C++ compiler, as the comments describe. If linking fails, check that both compilers are from compatible toolchains.
• Self-contained headers: compile a file containing only #include "sample-header.h" as C and as C++; it should produce no errors or warnings.
• Syntax highlighting: open sample-header.h and sample-header-only.hpp in your viewer; a .h file can be C or C++, so check which highlighting it picks.
• Upload filters: some systems block or rename source files. Try the samples to see whether .h, .hpp and .c files pass through unchanged.

Free to use for testing, teaching and demos, commercially or not, with no attribution needed. A link back to this page is always appreciated.

Questions

H files, frequently asked