Dynamic Linking

Dynamic linking

Linux loads shared libraries at startup or on demand through ld.so. This skill builds versioned shared objects, places them where the loader finds them, and diagnoses the failures in between.

Contract

Inputs

• The failing binary or the library to build: required.
• The intended library location: required for search-path work.
• Whether deployment must be relocatable: required before choosing $ORIGIN, RPATH, or RUNPATH.
• Root access: required only when registering a library system-wide with ldconfig.

Procedure

1. Build the shared library with a soname. The soname is what executables record and what ldconfig maintains. Done when: readelf -d libmylib.so.1.2.3 prints the intended SONAME.

gcc -fPIC -c src/mylib.c -o mylib.o
gcc -shared -Wl,-soname,libmylib.so.1 mylib.o -o libmylib.so.1.2.3
ln -s libmylib.so.1.2.3 libmylib.so.1   # loader name
ln -s libmylib.so.1     libmylib.so     # linker name for -lmylib

2. Bump versions by ABI change, not by habit. Done when: the bump class matches the change.

3. Embed the runtime search path. RPATH is searched before LD_LIBRARY_PATH; RUNPATH after it. Prefer RUNPATH for deployed binaries because environment variables then keep control. -Wl,--enable-new-dtags selects RUNPATH and is the modern linker default. $ORIGIN expands to the directory holding the binary, which makes an install tree relocatable. Done when: readelf -d myapp shows the intended tag and value.

gcc main.c -L./lib -lmylib \
    -Wl,-rpath,'$ORIGIN/../lib' -Wl,--enable-new-dtags -o myapp
readelf -d myapp | grep -E 'RPATH|RUNPATH'
chrpath -l myapp                 # show
chrpath -r '/new/path' myapp     # rewrite on an existing binary

4. Know the search order to predict a failure. ld.so searches, in order: DT_RPATH when no DT_RUNPATH exists, then LD_LIBRARY_PATH (ignored for setuid binaries), then DT_RUNPATH, then the /etc/ld.so.cache built by ldconfig, then /lib and /usr/lib. Done when: the failing library is placed at a search step that the deployment controls.

LD_DEBUG=libs ./myapp   # trace each resolution decision
ldd -v ./myapp          # resolved paths plus version requirements

5. Load a plugin with dlopen and dlsym. Clear dlerror() before each call; dlsym reports success through a null return from it, not from the pointer. Link with -ldl on glibc before 2.34; glibc 2.34 and later fold dlfcn into libc. Done when: the plugin loads, its entry point runs, and dlclose releases it.

#include <dlfcn.h>

typedef int (*plugin_fn_t)(const char *input);

void load_plugin(const char *path) {
    void *handle = dlopen(path, RTLD_NOW | RTLD_LOCAL);
    if (!handle) {
        fprintf(stderr, "dlopen: %s\n", dlerror());
        return;
    }
    dlerror();  // clear any error state before dlsym
    plugin_fn_t fn = (plugin_fn_t)dlsym(handle, "plugin_run");
    const char *err = dlerror();
    if (err) {
        fprintf(stderr, "dlsym: %s\n", err);
        dlclose(handle);
        return;
    }
    fn("hello");
    dlclose(handle);
}

6. Interpose a function with LD_PRELOAD. The preloaded library is searched first, so its symbols win. RTLD_NEXT finds the next definition in the chain. Done when: running with LD_PRELOAD=... shows the interception and the real call still works.

#define _GNU_SOURCE
#include <dlfcn.h>
#include <stdio.h>

void *malloc(size_t size) {
    static void *(*real_malloc)(size_t) = NULL;
    if (!real_malloc)
        real_malloc = (void *(*)(size_t))dlsym(RTLD_NEXT, "malloc");
    void *ptr = real_malloc(size);
    fprintf(stderr, "malloc(%zu) = %p\n", size, ptr);
    return ptr;
}

gcc -shared -fPIC -o myinterpose.so myinterpose.c -ldl
LD_PRELOAD=./myinterpose.so ./myapp

7. Export only the intended symbols. Build with -fvisibility=hidden and mark the public API visibility("default"), or restrict exports with a version script. Done when: nm -D --defined-only libmylib.so lists the public API and nothing else.

__attribute__((visibility("default"))) int public_api(void) { return 42; }

# mylib.map
MYLIB_1.0 {
    global:
        mylib_init;
        mylib_process;
    local:
        *;
};

gcc -shared -fPIC -fvisibility=hidden -Wl,--version-script=mylib.map \
    mylib.c -o libmylib.so

8. Diagnose the common failures. Done when: each reported error maps to its row and the fix is applied.

Failure and recovery

Output

The running binary or loaded plugin, plus the resolving evidence: ldd output, the SONAME and RUNPATH lines from readelf -d, or the interposition trace. Deep details on search paths, $ORIGIN, and version scripts are in references/ld-rpath-soname.md.