Common C++ Error Messages #2 – Undefined reference

Introduction

In this article I’ll be looking at the “undefined reference” error message (or “unresolved external symbol, for Visual C++ users). This is not actually a message from the compiler, but is emitted by the linker, so the first thing to do is to understand what the linker is, and what it does.

Linker 101

To understand the linker, you have to understand how C++ programs are built. For all but the very simplest programs, the program is composed of multiple C++ source files (also known as “translation units”). These are compiled separately, using the C++ compiler, to produce object code files (files with a .o or a .obj extension) which contain machine code. Each object code file knows nothing about the others, so if you call a function from one object file that exists in another, the compiler cannot provide the address of the called function.

This is where the the linker comes in. Once all the object files have been produced, the linker looks at them and works out what the final addresses of functions in the executable will be. It then patches up the addresses the compiler could not provide. It does the same for any libraries (.a and .lib files) you may be using. And finally it writes the executable file out to disk.

The linker is normally a separate program from the compiler (for example, the GCC linker is called ld) but will normally be called for you when you use your compiler suite’s driver program (so the GCC driver g++ will call ld for you).

Traditionally, linker technology has lagged behind compilers, mostly because it’s generally more fun to build a compiler than to build a linker. And linkers do not necessarily have access to the source code for the object files they are linking. Put together, you get a situation where linker errors, and the reasons for them, can be cryptic in the extreme.

Undefined reference

Put simply, the “undefined reference”  error means you have a reference (nothing to do with the C++ reference type) to a name (function, variable, constant etc.) in your program that the linker cannot find a definition for when it looks through all the object files and libraries that make up your project. There are any number of reasons why it can’t find the definition – we’ll look at the commonest ones now.

No Definition

Probably the most common reason for unresolved reference errors is that you simply have not defined the thing you are referencing. This code illustrates the problem:

int foo();

int main() {
    foo();
}

Here, we have a declaration of the function foo(), which we call in main(),  but no definition. So we get the error (slightly edited for clarity):

a.cpp:(.text+0xc): undefined reference to `foo()'
error: ld returned 1 exit status

The way to fix it is to provide the definition:

int foo();

int main() {
    foo();
}

int foo() {
    return 42;
}

 

Wrong Definition

Another common error is to provide a definition that does not match up with declaration (or vice versa). For example, if the code above we had provided a definition of foo() that looked like this:

int foo(int n) {
    return n;
}

then we would still get an error from the linker because the signatures (name, plus parameter list types) of the declaration and definition don’t match, so the definition actually defines a completely different function from the one in the declaration. To avoid this problem, take some care when writing declarations and definitions, and remember that things like references, pointers and const all count towards making a function signature unique.

Didn’t Link Object File

This is another common problem. Suppose you have two C++ source files:

// f1.cpp
int foo();

int main() {
    foo();
}

and:

// f2.cpp
int foo() {
    return 42;
}

If you compile f1.cpp on its own you get this:

f1.cpp:(.text+0xc): undefined reference to `foo()'

and if you compile f2.cpp on its own, you get this even more frightening one:

crt0_c.c:(.text.startup+0x39): undefined reference to `WinMain@16

In this situation, you need to compile both the the source files on the same command line, for example, using GCC:

$ g++ f1.cpp f2.cpp -o myprog

or if you have compiled them separately down to object files:

$ g++ f1.o f2.o -o myprog

For further information on compiling and linking multiple files in C++, particularly with GCC, please see my series of three blog articles starting here.

 

Wrong Project Type

The linker error regarding WinMain  above can occur in a number of situations, particularly when you are using a C++ IDE such as CodeBlocks or Visual Studio. These IDEs offer you a number of project types such as “Windows Application” and “Console Application”. If you want to write a program that has a int main() function in it, always make sure that you choose “Console Application”, otherwise the IDE may configure the linker to expect to find a WinMain() function instead.

No Library

To understand this issue, remember that a header file (.h) is not a library. The linker neither knows nor cares about header files – it cares about .a and .lib files. So if you get a linker error regarding a name that is in a library you are using, it is almost certainly because you have not linked with that library. To perform the linkage, if you are using an IDE you can normally simply add the library to your project, if using the command line, once again please see my series of blog articles on the GCC command line starting here, which describes some other linker issues you may have.

Conclusion

The unresolved reference error can have many causes, far from all of which have been described here. But it’s not magic – like all errors it means that you have done something wrong, in you code and/or your project’s configuration, and you need to take some time to sit down, think logically, and figure out what.