Shared libraries and the dynamic linker

Dynamic linking, and the cache that makes it fast

A statically linked program contains every library function it uses and depends on nothing at run time. A dynamically linked one — which is almost everything — contains only references, and the dynamic linker resolves them when the program starts. ldd prints that list for a binary, showing each required soname and the file it currently resolves to; a line reading "not found" is precisely the failure this objective is about.

Searching the whole filesystem on every program start would be slow, so the linker consults a cache: /etc/ld.so.cache, a binary file built by ldconfig from the directories listed in /etc/ld.so.conf and the files included from /etc/ld.so.conf.d/. This is why installing a library into a new directory is not enough — until you add the directory and run ldconfig, the linker does not know to look there.

LD_LIBRARY_PATH is the override: directories in it are searched before the cache. It is useful for testing and for running a program against a library you have not installed system-wide, and it is a poor permanent answer, because it applies to whatever inherits the environment rather than to the one program that needed it.

Sonames, and why versions do not break everything

A library file is usually named something like libfoo.so.1.2.3, with a symlink libfoo.so.1 pointing at it — that shorter name is the soname, and it is what a program records. The scheme means a compatible bug-fix release can replace the file and every program keeps working, while an incompatible release gets a new soname and the two can sit side by side. ldconfig is also what creates those symlinks, which is the second reason running it matters.

That makes three names for one library, and a question will lay all three out and ask which one the program holds. The readline history library ships as the file /usr/lib/x86_64-linux-gnu/libhistory.so.8.1; libhistory.so.8 is the soname symlink beside it, carrying the interface version and nothing finer; and libhistory.so, the unversioned linker name, is shipped only in the development package and is what the compiler follows at build time. The full file name is too specific to record and the unversioned one too vague, so the soname is the one written into the binary — which is why an update to .8.2 needs no rebuild and a move to .so.9 installs alongside rather than over the top.

The two commands sit on opposite sides of the bin/sbin split, and a question will use the full path rather than the name to test whether you know which. ldd only reports, so anyone may run it and it is /usr/bin/ldd. ldconfig writes the system-wide cache, so it is an administrative tool at /usr/sbin/ldconfig, reached as /sbin/ldconfig on distributions that have not merged the two. Being unable to run ldconfig as an ordinary user is the rule working, not a broken install.

$ /usr/bin/ldd /usr/local/bin/reportlibvendor.so.1 => not foundlibc.so.6 => /lib/x86_64-linux-gnu/libc.so.6# the file exists in /opt/vendor/lib — the linker has not been told$ echo /opt/vendor/lib > /etc/ld.so.conf.d/vendor.conf$ /usr/sbin/ldconfig$ ldconfig -p | grep libvendorlibvendor.so.1 (libc6,x86-64) => /opt/vendor/lib/libvendor.so.1