rpath

This article is about the programming term. For the company, see rPath.

rpath is a term in programming which refers to a run-time search path hard-coded in an executable file or library, used during dynamic linking to find the libraries the executable or library requires.

Specifically it encodes a path to shared libraries into the header of an executable (or another shared library). This RPATH header value (so named in the Executable and Linkable Format header standards) may either override or supplement the system default dynamic linking search paths.

The rpath of a executable or shared library is an optional entry in the .dynamic section of ELF the executable or shared libraries, with the type DT_RPATH, called the DT_RPATH attribute.

It can be stored there at link time by the linker and can be modified (or, possibly also created) later using tools like chrpath and patchelf.

Use of the DT_RPATH entry by the dynamic linker

The different dynamic linkers for ELF implement the use the DT_RPATH attribute in different ways.

GNU ld.so

The dynamic linker of the GNU C Library and its derivative Embedded GLIBC implement a rather complicated algorithm for searching for shared libraries. The basic search order is:

1. The paths in the DT_RPATH dynamic section attribute of the binary if present and DT_RUNPATH attribute does not exist
2. The paths in the environment variable LD_LIBRARY_PATH, unless the executable is a setuid/setgid binary, in which case it is ignored. LD_LIBRARY_PATH can be overridden by calling the dynamic linker with the option --library-path (e.g. /lib/ld-linux.so.2 --library-path $HOME/mylibs myprogram)
3. The paths in the DT_RUNPATH dynamic section attribute of the binary if present.
4. Lookup based on the ldconfig cache file (often located at /etc/ld.so.cache) which contains a compiled list of candidate libraries previously found in the augmented library path. If, however, the binary was linked with -z nodeflib linker option, libraries in the default library paths are skipped.
5. In the default path /lib, and then /usr/lib. If the binary was linked with -z nodeflib linker option, this step is skipped.

Notes:

• The option --inhibit-rpath LIST of the dynamic linker instructs it to ignore DT_RPATH and DT_RUNPATH attributes of the object names in LIST.
• Libraries specified by the environment variable LD_PRELOAD are loaded before any library searching takes place.
• Static libraries are searched and linked into the ELF file at link time and are not linked at run time.

The role of GNU ld

The GNU Linker (GNU ld) implements a feature which it calls "new-dtags":

If the new-dtags feature is enabled in the linker (at run time using --enable-new-dtags), GNU ld, besides setting the DT_RPATH attribute, also sets the DT_RUNPATH attribute, which is checked by the dynamic linker at run time and if it finds an DT_RUNPATH attribute, it ignores the value of the DT_RPATH attribute, which with the effect that LD_LIBRARY_PATH is checked next and the paths in the DT_RUNPATH attribute are only searched after it.

This means that in such configurations, the paths in LD_LIBRARY_PATH *are* searched before these given at link time using -rpath if --enable-new-dtags was active.

Solaris ld.so

The dynamic linker of Solaris, specifically /lib/ld.so of SunOS 5.8 and similar systems looks for libraries in the directories specified in the LD_LIBRARY_PATH variable before looking at the DT_RPATH attribute.

External links

• Autobook section containing brief discussion of rpath
• chrpath - a tool to change the DT_RPATH attribute of an executable and convert it to an DT_RUNPATH attribute
• patchELF - a small utility to modify the dynamic linker and DT_RUNPATH attribute of ELF executables.