How do header and source files in C work?

Question

I've perused the possible duplicates, however none of the answers there are sinking in.

tl;dr: How are source and header files related in C? Do projects sort out declaration/definition dependencies implicitly at build time?

I'm trying to understand how the compiler understands the relationship between .c and .h files.

Given these files:

header.h:

int returnSeven(void);

source.c:

int returnSeven(void){
    return 7;
}

main.c:

#include <stdio.h>
#include <stdlib.h>
#include "header.h"
int main(void){
    printf("%d", returnSeven());
    return 0;
}

Will this mess compile? I'm currently doing my work in NetBeans 7.0 with gcc from Cygwin which automates much of the build task. When a project is compiled will the project files involved sort out this implicit inclusion of source.c based on the declarations in header.h?

Yes, this will compile (and why do you think it's a "mess"?). The concepts to learn about are **compilation units** and **linkage**. — Jesper, May 05 '11 at 21:56
Thanks **Jesper**; Haha, it's not a mess, I suppose that word is best reserved for describing my brain, reading between 3 beginner level `C` books. I'll certainly look into *compilation units* and *linkage*, however for the sake of focusing on learning syntax, I'll let **NetBeans** + **gcc** figure this out for me. Given that, whenever a given header file has declarations for which definitions exist elsewhere in the project, the inclusion of that header file is sufficient to provide access to the defined functionality, and the compiler will sort out the details? — Dan Lugg, May 05 '11 at 22:00
Also I recommend compiling this by hand. `gcc main.c -c -o main.o`, `gcc source.c -c -o source.o`, `gcc main.o source.o -o program` will compile that. It makes it easy to see the separate compiled units and the linking at the end. — alternative, May 05 '11 at 22:02

score 104 · Accepted Answer · answered May 05 '11 at 22:16

Converting C source code files to an executable program is normally done in two steps: compiling and linking.

First, the compiler converts the source code to object files (*.o). Then, the linker takes these object files, together with statically-linked libraries and creates an executable program.

In the first step, the compiler takes a compilation unit, which is normally a preprocessed source file (so, a source file with the contents of all the headers that it #includes) and converts that to an object file.

In each compilation unit, all the functions that are used must be declared, to let the compiler know that the function exists and what its arguments are. In your example, the declaration of the function returnSeven is in the header file header.h. When you compile main.c, you include the header with the declaration so that the compiler knows that returnSeven exists when it compiles main.c.

When the linker does its job, it needs to find the definition of each function. Each function has to be defined exactly once in one of the object files - if there are multiple object files that contain the definition of the same function, the linker will stop with an error.

Your function returnSeven is defined in source.c (and the main function is defined in main.c).

So, to summarize, you have two compilation units: source.c and main.c (with the header files that it includes). You compile these to two object files: source.o and main.o. The first one will contain the definition of returnSeven, the second one the definition of main. Then the linker will glue those two together in an executable program.

About linkage:

There is external linkage and internal linkage. By default, functions have external linkage, which means that the compiler makes these functions visible to the linker. If you make a function static, it has internal linkage - it is only visible inside the compilation unit in which it is defined (the linker won't know that it exists). This can be useful for functions that do something internally in a source file and that you want to hide from the rest of the program.

Oliver Charlesworth · Answer 2 · 2011-05-05T22:08:15.957

The C language has no concept of source files and header files (and neither does the compiler). This is merely a convention; remember that a header file is always #included into a source file; the preprocessor literally just copy-pastes the contents, before proper compilation begins.

Your example should compile (foolish syntax errors notwithstanding). Using GCC, for example, you might first do:

gcc -c -o source.o source.c
gcc -c -o main.o main.c

This compiles each source file separately, creating independent object files. At this stage, returnSeven() has not been resolved inside main.c; the compiler has merely marked the object file in a way that states that it must be resolved in the future. So at this stage, it's not a problem that main.c can't see a definition of returnSeven(). (Note: this is distinct from the fact that main.c must be able to see a declaration of returnSeven() in order to compile; it must know that it is indeed a function, and what its prototype is. That is why you must #include "source.h" in main.c.)

You then do:

gcc -o my_prog source.o main.o

This links the two object files together into an executable binary, and performs resolution of symbols. In our example, this is possible, because main.o requires returnSeven(), and this is exposed by source.o. In cases where everything doesn't match up, a linker error would result.

(Note: this is distinct from the fact that main.c must be able to see a declaration of returnSeven() : I am being pedantic, but this is not entirely correct. The compiler will happily compile (with a warning in C99) this code, and the linker resolve it, usually with bad effects. e.g. in file a.c, call `x=bob(1,2,3,4)` and in file b.c, `void bob(char *a){}` will compile, link and run. — mattnz, May 05 '11 at 23:49
Absolutely world class answer. Love the minimalist GCC compiler instructions examples — Dean P, Jul 18 '17 at 13:58

score 15 · Answer 3 · answered May 05 '11 at 22:25

There is nothing magic about compilation. Nor automatic!

Header files basically provide information to the compiler, almost never code.
That information alone, is usually not enough to create a full program.

Consider the "hello world" program (with the simpler puts function):

#include <stdio.h>
int main(void) {
    puts("Hello, World!");
    return 0;
}

without the header, the compiler does not know how to deal with puts() (it is not a C keyword). The header lets the compiler know how to manage the arguments and return value.

How the function works, however, is not specified anywhere in this simple code. Somebody else has written the code for puts() and included the compiled code in a library. The code in that library is included with the compiled code for your source as part of the compilation process.

Now consider you wanted your own version of puts()

int main(void) {
    myputs("Hello, World!");
    return 0;
}

Compiling just this code gives an error because the compiler has no information about the function. You can provide that information

int myputs(const char *line);
int main(void) {
    myputs("Hello, World!");
    return 0;
}

and the code now compiles --- but does not link, ie does not produce an executable, because there is no code for myputs(). So you write the code for myputs() in a file called "myputs.c"

#include <stdio.h>
int myputs(const char *line) {
    while (*line) putchar(*line++);
    return 0;
}

and you have to remember to compile both your first source file and "myputs.c" together.

After a while your "myputs.c" file has expanded to a hand full of functions and you need to include the information about all the functions (their prototypes) in the source files that want to use them.
It is more convenient to write all the prototypes in a single file and #include that file. With the inclusion you run no risk of making a mistake when typing the prototype.

You still have to compile and link all the code files together though.

When they grow even more, you put all the already compiled code in a library ... and that's another story :)

score 6 · Answer 4 · answered May 05 '11 at 22:01

Header files are used to separate the interface declarations which correspond to the implementations in the source files. They're abused in other ways, but this is the common case. This isn't for the compiler, it's for the humans writing the code.

Most compilers don't actually see the two files separately, they are combined by the preprocessor.

score 2 · Answer 5 · answered May 05 '11 at 21:58

The compiler itself has no specific "knowledge" of relationships between source files and header files. Those types of relationships are typically defined by project files (e.g., makefile, solution, etc.).

The given example appears as if it would compile correctly. You would need to compile both source files and then the linker would need both object files to produce the executable.

How do header and source files in C work?

5 Answers5

Linked