After having worked several years in C++ development with Visual Studio, here’s a quite comprehensive compilation of the linker error’s I’ve encountered

Possible reasons for linker errors

Compiler errors most often point to the exact location of the problem. Linker errors in (Visual Studio) C++ are not that programmer-friendly – it’s more of a guesswork, as various reasons lead to the same error message “LNK2019: unresolved external symbol”. Here are some hints (vaguely ordered by occurence in every-day work):

• The importing project is missing the reference to the exporting project (or the library is not specified in the imports, respectively)
• Missing dllimport/dllexport statement (usually a macro) before class/function declaration
• Build problems – the file from which the class/function is imported does not match with the header (e.g. the lib file is out of date for some reason)
• Function/member variable declared but not implemented
• Function is implemented with a diffent signature than it was declared with (different name (e.g. typo), different parameters, different return type)
• Mismatching Character Encoding settings (unicode/non-unicode) in the dlls (which will cause that the signature is different)
• Mismatching setting for “treat wchar_t as builtin type” (dumpbin/undname is really useful in this case, as it will show the varying types)
• Problems with the macro that defines the dllimport/dllexport modifier
• Functions only – the header declaring the function is not included in the file where it is defined
• The header declaring the class/function is not included in any file in the exporting dll (or that file is excluded from compilation)
• The calling convention (such as __cdecl) is different in the declaration and the implementation
• If the linker error involves the main/WinMain function, consider that in UNICODE it is wmain/wWinMain (preferably use _tmain/_tWinMain), or the subsystem linker setting might be wrong – if /SUBSYSTEM:WINDOWS is specified, the main function has to be WinMain (rather use _tWinMain), if /SUBSYSTEM:CONSOLE is specified, the main function has to be main (rather use _tmain).

Additional information is available on the LNK2019 MSDN page

Tools for resolving linker errors

The best tool is your sharp mind, the following two however will be useful in some cases:

• “undname” undecorates mangled names (i.e. converts something like “?TestFunction@@YAHPBD@Z” to “int __cdecl TestFunction(char const *)”)
• “dumpbin” shows all exported symbols of a lib/dll file (you can also use your favourite text editor to find the function export in the dll/lib as these are stored in readable text within the binary)

These are mostly useful when there’s a problem with the function signature or the exporting file does not match the exporting headers.

Both need to be started from the Visual Studio Command Prompt.

Example code producing a linker error due to a missing function implementation

(TestDeclaration.h)

THISPROJECT_EXPORT int TestFunction(const char* pChar);
int TestFunction(const int* pChar)
{
	return 0;
}

(TestUsage.cpp)

int i = TestFunction("hi");

As the function is not implemented anywhere, the following linker error will result:

TestUsage.obj : error LNK2019: 
unresolved external symbol "__declspec(dllimport) int __cdecl TestFunction(char const *)" (__imp_?TestFunction@@YAHPBD@Z) 
referenced in function "public: __thiscall TestUsage::TestUsage(void)" (??0TestUsage@@QAE@XZ)

undname

The usage of undname (undecorates names) then looks like this:

c:\Program Files\Microsoft Visual Studio 9.0\VC>undname ?TestFunction@@YAHPBD@Z
Microsoft (R) C++ Name Undecorator
Copyright (C) Microsoft Corporation. All rights reserved.

Undecoration of :- "?TestFunction@@YAHPBD@Z"
is :- "int __cdecl TestFunction(char const *)"

dumpbin

The usage of dumpbin looks like this (may produce tons of output, so it’s streamed to a file):

c:\Program Files\Microsoft Visual Studio 9.0\VC>dumpbin -exports C:\dev\linkertest\LinkerTest.lib > C:\dev\linkertest\dump.txt

Microsoft (R) COFF/PE Dumper Version 9.00.30729.01
Copyright (C) Microsoft Corporation.  All rights reserved.

The dump.txt file then looks like this:

File Type: LIBRARY
[snip...]
                  ?TestFunction@@YAHPBD@Z (int __cdecl TestFunction(char const *))