I was reading the GNU documentation on the GCC linker's --wrap option, which can be used to mock functions for testing.

https://ftp.gnu.org/old-gnu/Manuals/ld-2.9.1/html_node/ld_3.html says the following:

--wrap symbol

Use a wrapper function for symbol. Any undefined reference to symbol will be resolved to __wrap_symbol. Any undefined reference to __real_symbol will be resolved to symbol. This can be used to provide a wrapper for a system function. The wrapper function should be called __wrap_symbol. If it wishes to call the system function, it should call __real_symbol.

I've noticed that it says Any undefined reference to symbol will be resolved to __wrap_symbol, but it doesn't say what exactly an undefined reference to symbol means. Does anyone know specifically what is considered undefined?

I'm confused because I created an example program that successfully mocks the read function (it's compiled with gcc test.c -o test -Wl,--wrap=read to enable mocking). How come the linker considers this symbol undefined? I included unistd.h, so shouldn't that make read defined? I thought the documentation said --wrap only works on undefined symbols?

#include <stdio.h>
#include <string.h>
#include <unistd.h>

#define DUMMY_STR "I don't care because this function is mocked."
#define DUMMY_LEN (strlen(DUMMY_STR))

ssize_t __wrap_read(int fd, void *buf, size_t count)
{
   sprintf(buf, DUMMY_STR);
   return DUMMY_LEN;
}

int main()
{
   char buf[128] = {'\0'};
   puts("Press anything, then ENTER, to continue");
   read(1, buf, sizeof(buf) - 1);
   puts(buf);
   return 0;
}