Directories Searched by the Runtime Linker

By default, the runtime linker knows of only one standard place to look for libraries, /usr/lib when processing 32–bit objects, and /usr/lib/64 when processing 64–bit objects. All other directories to be searched must be added to the runtime linker's search path explicitly.

When a dynamic executable or shared object is linked with additional shared objects, these shared objects are recorded as dependencies that must be located again during process execution by the runtime linker. During the link-edit, one or more search paths can be recorded in the output file. These search paths are used by the runtime linker to locate any shared object dependencies. These recorded search paths are referred to as a runpath.

Objects may be built with the -z nodefaultlib option to suppress any search of the default locations at runtime. Use of this option implies that all the dependencies of an object can be located using its runpaths. Without this option, which is the most common case, no matter how you augment the runtime linker's library search path, its last element is always /usr/lib for 32–bit objects and /usr/lib/64 for 64–bit objects.

Default search paths can be administrated using a runtime configuration file. See “Configuring the Default Search Paths”. However the creator of an object should not rely on the existence of this file, and should always ensure that their object can locate its dependencies with only its runpaths or standard system defaults.

You can use the -R option, which takes a colon-separated list of directories, to record a runpath in a dynamic executable or shared object. The following example records the runpath /home/me/lib:/home/you/lib in the dynamic executable prog.

$ cc -o prog main.c -R/home/me/lib:/home/you/lib -Lpath1 \
-Lpath2 file1.c file2.c -lfoo -lbar

The runtime linker uses these paths, then the default location /usr/lib, to locate any shared object dependencies. In this case, this runpath is used to locate libfoo.so.1 and libbar.so.1.

The link-editor accepts multiple -R options and concatenates each of these specifications, separated by a colon. Thus, the previous example can also be expressed as:

$ cc -o prog main.c -R/home/me/lib -Lpath1 -R/home/you/lib \
-Lpath2 file1.c file2.c -lfoo -lbar

For objects that may be installed in various locations, the $ORIGIN dynamic string token provides a flexible means of recording a runpath. See “Locating Associated Dependencies”.

A historic alternative to specifying the -R option is to set the environment variable LD_RUN_PATH, and make this available to the link-editor. The scope and function of LD_RUN_PATH and -R are identical, but when both are specified, -R supersedes LD_RUN_PATH.