Bug#807383: gcc-doc: Manpage documentation of -l is incorrect

[Dima Kogan <dima@secretsauce.net>]

Package: gcc-doc
Version: 5:4.9.2-1
Severity: normal

Hi. This relates to several details of linking, and I'm not sure if this
is a Debian or upstream bug.

The 'gcc' manpage says this:

       -llibrary
           ...
           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.
           ...
           Normally the files found this way are library files---archive
           files whose members are object files. ...

This is not what actually happens. For instance, I have libarpack2-dev
installed. This ships both libarpack.a and libarpack.so. I build a
simple application like this:

$ gcc -o tst -larpack tst.c

Using strace to see what files are actually opened, I see this:

[pid 13833] open("/usr/lib/gcc/x86_64-linux-gnu/5/libarpack.so", O_RDONLY) = -1 ENOENT (No such file or directory)
[pid 13833] open("/usr/lib/gcc/x86_64-linux-gnu/5/libarpack.a", O_RDONLY) = -1 ENOENT (No such file or directory)
[pid 13833] open("/usr/lib/gcc/x86_64-linux-gnu/5/../../../x86_64-linux-gnu/libarpack.so", O_RDONLY) = -1 ENOENT (No such file or directory)
[pid 13833] open("/usr/lib/gcc/x86_64-linux-gnu/5/../../../x86_64-linux-gnu/libarpack.a", O_RDONLY) = -1 ENOENT (No such file or directory)
[pid 13833] open("/usr/lib/gcc/x86_64-linux-gnu/5/../../../../lib/libarpack.so", O_RDONLY) = 9
[pid 13833] open("/usr/lib/gcc/x86_64-linux-gnu/5/../../../../lib/libarpack.so", O_RDONLY) = 10

So in each path in the list we look for the .so and then the .a. The
manpage however implies that we only look for the .a, and while we DO
look for it, this isn't the first choice.