What is the meaning of -lm in GCC?

Question

When I compile some C code with gcc, it needs adding -lm. For example, when I want to use fmax in my program, I must use the following command:

gcc myprogram.c -lm

What happens to my program by adding -lm? What does -lm mean?

Answer 1

TLDNR: math.h is not a part of the standard C library, so you have to link to it!

-llibrary searches the library library while linking. The m stands for libm, the library that contains <math.h>. For more information, see these couple links.

@luantkow's answer is really good but long! Here's a short version if you don't want to read! ¯\_(ツ)_/¯

Answer 2

Let's say you have the main.c file:

#include <math.h>
#include <stdio.h>

float my_foo(float a, float b)
{
    return fmax(a, b);
}

int main()
{
    printf("%f\n", my_foo(4.5, 3.1));
    return 0;
}

If you try to compile it without the -lm flag, you will receive am undefined reference error:

main.o: In function `my_foo':
main.c:(.text+0x1d): undefined reference to `fmax'
collect2: error: ld returned 1 exit status

This is because the linker does not know any implementation of the fmax function. You have to provide it.

In gcc man, you can find the following description of the -llibrary flag:

Search the library named library when linking. (The second alternative with the library as a separate argument is only for POSIX compliance and is not recommended.)

It makes a difference where in the command you write this option; the linker searches and processes libraries and object files in the order they are specified. Thus, foo.o -lz bar.o searches library z after file foo.o but before bar.o. If bar.o refers to functions in z, those functions may not be loaded.

The linker searches a standard list of directories for the library, which is actually a file named liblibrary.a. The linker then uses this file as if it had been specified precisely by name.

The directories searched include several standard system directories plus any that you specify with -L.

Normally the files found this way are library files---archive files whose members are object files. The linker handles an archive file by scanning through it for members which define symbols that have so far been referenced but not defined. But if the file that is found is an ordinary object file, it is linked in the usual fashion. The only difference between using an -l option and specifying a file name is that -l surrounds library with lib and .a and searches several directories.

It looks that I have the libm.a file stored at /usr/lib/x86_64-linux-gnu/libm.a:

$ find /usr/lib -iname libm.a

/usr/lib/x86_64-linux-gnu/libm.a

You can check that libm.a contains the definition of fmax:

$ nm /usr/lib/x86_64-linux-gnu/libm.a --defined-only | grep fmax

[...]
s_fmax.o:
0000000000000000 W fmax
[...]

In case the command above will result in an error with following result:

$ nm /usr/lib/x86_64-linux-gnu/libm.a

nm: /usr/lib/x86_64-linux-gnu/libm.a: file format not recognized

It may be caused by the fact that your distribution provides libm.a as a linker script.

$ file /usr/lib/x86_64-linux-gnu/libm.a

/usr/lib/x86_64-linux-gnu/libm.a: ASCII text

File /usr/lib/x86_64-linux-gnu/libm.a

/* GNU ld script
*/
OUTPUT_FORMAT(elf64-x86-64)
GROUP ( /usr/lib/x86_64-linux-gnu/libm-2.31.a /usr/lib/x86_64-linux-gnu/libmvec.a )

The script basically informs the linker to try to link libm-2.31.a and libmvec.a. See the GROUP description in Using LD, the GNU linker.

So you should be able to verify that the fmax implementation is provided in libm-2.31.a with:

$ nm /usr/lib/x86_64-linux-gnu/libm-2.31.a --defined-only 2> /dev/null | grep -w fmax

0000000000000000 W fmax