Linker and Libraries Guide

Relocation Errors

The most common relocation error occurs when a symbol cannot be found. This condition results in an appropriate runtime linker error message together with the termination of the application. In the following example, the symbol bar, which is referenced in the file libfoo.so.1, cannot be located.


$ ldd prog
        libfoo.so.1 =>   ./libfoo.so.1
        libc.so.1 =>     /lib/libc.so.1
        libbar.so.1 =>   ./libbar.so.1
        libm.so.2 =>     /lib/libm.so.2
$ prog
ld.so.1: prog: fatal: relocation error: file ./libfoo.so.1: \
    symbol bar: referenced symbol not found
$

During the link-edit of a dynamic executable, any potential relocation errors of this sort are flagged as fatal undefined symbols. See Generating an Executable Output File for examples. However, a runtime relocation error can occur if a dependency located at runtime is incompatible with the original dependency referenced as part of the link-edit. In the previous example, prog was built against a version of the shared object libbar.so.1 that contained a symbol definition for bar.

The use of the -z nodefs option during a link-edit suppresses the validation of an objects runtime relocation requirements. This suppression can also lead to runtime relocation errors.

If a relocation error occurs because a symbol used as an immediate reference cannot be found, the error condition occurs immediately during process initialization. With the default mode of lazy binding, if a symbol used as a lazy reference cannot be found, the error condition occurs after the application has gained control. This latter case can take minutes or months, or might never occur, depending on the execution paths exercised throughout the code.

To guard against errors of this kind, the relocation requirements of any dynamic executable or shared object can be validated using ldd(1).

When the -d option is specified with ldd(1), every dependency is printed and all immediate reference relocations are processed. If a reference cannot be resolved, a diagnostic message is produced. From the previous example, the -d option would result in the following error diagnostic.


$ ldd -d prog
        libfoo.so.1 =>   ./libfoo.so.1
        libc.so.1 =>     /lib/libc.so.1
        libbar.so.1 =>   ./libbar.so.1
        libm.so.2 =>     /lib/libm.so.2
        symbol not found: bar           (./libfoo.so.1)

When the -r option is specified with ldd(1), all immediate reference and lazy reference relocations are processed. If either type of relocation cannot be resolved, a diagnostic message is produced.