======Libraries: libm======

The ability to use programming libraries greatly enhances our capabilities, as we can use functions that others have created, instead of having to implement everything ourselves from ground up.

However, with the utilization of libraries, we need to provide additional input to the compiler so that all necessary data bits can be found.

We'll start by going through a simple example- square rooting.

In C, there is a math library (affectionately known as **libm**) that provides us with a set of math functions. Of them, 
**sqrt()** lets us calculate the square root.

=====Programming Documentation=====

From the man page (**man 3 sqrt**), we see the following:

<cli>
NAME
       sqrt, sqrtf, sqrtl - square root function

SYNOPSIS
       #include <math.h>

       double sqrt(double x);
       float sqrtf(float x);
       long double sqrtl(long double x);

       Link with -lm.
</cli>

=====Code=====

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

int main()
{
    double a = 144, b = 0;
    
    b = sqrt(a);
    
    printf("The square root of %f is %f\n", a, b);
    
    return(0);
}
</code>

=====Compiling, Take One=====

If we try to compile this code, we should get the following compiler message:

<cli>
lab46:~/src$ gcc -o math math.c  
/tmp/ccQNybzu.o: In function `main':
math.c:(.text+0x32): undefined reference to `sqrt'
collect2: ld returned 1 exit status
lab46:~/src$ 
</cli>

Note that there isn't a problem with the source code-- that actually compiled cleanly. What it is having a problem with is that it does not know where to find the **sqrt()** function (because it isn't in the Standard C Library, which is the only library included by default).

=====Compiling, Take Two=====
If you recall from the manual page information, we have to link it against the math library (using the **-lm** option to the compiler). Let's go ahead and do that:

<cli>
lab46:~/src$ gcc -o math math.c -lm
lab46:~/src$ 
</cli>

Success!

=====Verifying it works=====
At this point we can run it and make sure it works (square root of 144? 12.)

<cli>
lab46:~/src$ ./math
The square root of 144.000000 is 12.000000
lab46:~/src$ 
</cli>

=====Exploration=====
For those up for a deeper understanding of how things connect together, in your terminal do a **cd /lib**, followed by an **ls**... **/lib** is a traditional location for libraries on UNIX systems... here you should be able to find:

  * The C library: libc.so.6
  * The Math library: libm.so.6

Plus, by hunting around in the other "**lib**" directories (**/usr/lib**, **/usr/local/lib**, among others), you can find yet more libraries.

Note that there's a mechanism in place that aids the compiler in finding libraries if they are in these predefined locations. If you're using a library that is located elsewhere, you will need to also use the **-L** (note the CAPITAL L) option and specify a path.

=====Conclusion=====
Basically, to use a library, we need 2 things:

  - include any pertinent header files in our source code (and of course use said functions correctly)
  - at compile time, specify **-l** with the library name (dropping the preceding **lib** and suffixing **so.NUMBER** stuff)... so for **libm.so.6**, it would merely be **-lm**.