Mismatched return types and link-time symbol resolution

I've read that it's good practice for implementation files to include their corresponding header, as it allows certain type errors to be caught at compile-time instead of at link-time. However, while searching for an example of such an error, I ended up with the following code, which produces a result that I don't quite understand:

a.h:

char returnString(void);

int returnInt(void);

a.cpp:

// #include "a.h"
#include <string>

std::string returnString(void)
{
    return "Hi";
}

void returnInt(void)
{
    // return 1;
}

main.cpp:

#include "a.h"
#include <iostream>

int main(void)
{
    std::cout << returnString() << '\n';
    std::cout << returnInt() << '\n';

    return 0;
}

The declarations in a.h have a different return type from the definitions in a.cpp. This discrepancy is picked up by the compiler if a.h is included in its corresponding implementation file, a.cpp. However, if I comment out the inclusion (as shown above) and then try to compile and link with g++ main.cpp a.cpp, I get the following link-time error:

/usr/bin/ld: /tmp/ccgWiADF.o: in function 'main':
main.cpp:(.text+0x2c): undefined reference to 'returnString()'
collect2: error: ld returned 1 exit status

So, the linker seems to resolve the call to returnInt() to the definition in a.cpp, but cannot to the same for the call to returnString(). Why is this?

On this implementation, std::string has an ABI tag (to distinguish it from the pre-C++11 implementation). When it is used as the return type of returnString, the tag is automatically applied to returnString, which changes its mangled name. As a result, from the perspective of the linker, char returnString(void) and std::string returnString(void) have distinct names.

From GCC's documentation of abi_tag:

> The abi_tag attribute can be applied to a function, variable, or class declaration. It modifies the mangled name of the entity to incorporate the tag name, in order to distinguish the function or class from an earlier version with a different ABI; perhaps the class has changed size, or the function has a different return type that is not encoded in the mangled name.
>
> [...]
>
> When a type involving an ABI tag is used as the type of a variable or return type of a function where that tag is not already present in the signature of the function, the tag is automatically applied to the variable or function.

However, note that this is specific to this particular compiler and standard library. You should not assume this behavior in general.

From the current standard draft:

> For any definable item D with definitions in multiple translation units,
if D is a non-inline non-templated function or variable, or
if the definitions in different translation units do not satisfy the following requirements,
the program is ill-formed; a diagnostic is required only if the definable item is attached to a named module and a prior definition is reachable at the point where a later definition occurs.
Given such an item, for all definitions of D [...] that are reachable at any given program point, the following requirements shall be satisfied.

And then in the list of requirements it reads

> Each such definition shall consist of the same sequence of tokens [...]

The problem in your program is that you at one point you define returnString to be of type char() and at another point in the program you define it to be of type std::string(). During compilation the two definition points are not reachable from oneanother if you don't include the header "a.h". Thus the program is ill-formed NDR (no diagnostic required). The same applies to returnInt, but apparently the implementation chose to issue a diagnostic in one case and not in the other, which is standard conforming behaviour. Executing the program results in undefined behaviour.

This answer tells you why GCC issues a diagnostic in one case but not in the other.

As far as main is concerned, it only knows about returnString that returns a char*. When fully linked, there's a declaration for such a function, but there's no definition of it (hence the undefined reference).

Think of it as overloads sharing a same front-end name, but all having a distinct and unique back-end name.

Difference in return type will make you a different symbol/entity. Especially since you can't overload solely on the return type.