Run LD_DEBUG=help date to see all options (the program itself won’t execute):

$ LD_DEBUG=help date
Valid options for the LD_DEBUG environment variable are:

  libs       display library search paths
  reloc      display relocation processing
  files      display progress for input file
  symbols    display symbol table processing
  bindings   display information about symbol binding
  versions   display version dependencies
  all        all previous options combined
  statistics display relocation statistics
  unused     determine unused DSOs
  help       display this help message and exit

To direct the debugging output into a file instead of standard output
a filename can be specified using the LD_DEBUG_OUTPUT environment variable.

This is the most commonly used option. It shows every directory the dynamic linker checks when looking for a library, and which file it eventually loads.

# See where libm.so is being searched and found
LD_DEBUG=libs ls 2>&1 | head -30

# Sample output:
#      7543:   find library=libselinux.so.1 [0]; searching
#      7543:    search cache=/etc/ld.so.cache
#      7543:     /lib/x86_64-linux-gnu/libselinux.so.1
#      7543:     trying file=/lib/x86_64-linux-gnu/libselinux.so.1
#      7543:
#      7543:   find library=libc.so.6 [0]; searching
#      7543:    search cache=/etc/ld.so.cache
#      7543:     /lib/x86_64-linux-gnu/libc.so.6
#      7543:     trying file=/lib/x86_64-linux-gnu/libc.so.6

# More targeted: check library loading for your own program
LD_DEBUG=libs LD_LIBRARY_PATH=. ./prog 2>&1

# This tells you:
# 1. Which directories were searched (RPATH, LD_LIBRARY_PATH, /etc/ld.so.cache, default dirs)
# 2. Which .so file was actually opened
# 3. Which libraries were NOT found (look for "not found" in output)

When you have multiple libraries that define the same function (e.g., when using LD_PRELOAD), bindings tells you exactly which library each call resolved to.

# Using bindings to verify LD_PRELOAD is working correctly
LD_DEBUG=bindings LD_PRELOAD=libalt.so LD_LIBRARY_PATH=. ./prog 2>&1 | grep "x1\|x2"

# Sample output:
#  12345:    binding file ./prog [0] to libalt.so [0]: normal symbol `x1'
#  12345:    binding file ./prog [0] to libdemo.so [0]: normal symbol `x2'

# Checking which malloc() a program uses (useful after LD_PRELOAD)
LD_DEBUG=bindings LD_PRELOAD=./libmtrace.so ./prog 2>&1 | grep malloc

# Output shows malloc bound to your libmtrace.so (preloaded) not libc
#  99:    binding file ./prog to ./libmtrace.so: normal symbol `malloc'

Debug output goes to stderr by default. For long programs, this floods your terminal. Use LD_DEBUG_OUTPUT to redirect it to a file. You can also combine multiple keywords.

# Save all debug output to a file (pid is appended automatically)
LD_DEBUG=libs LD_DEBUG_OUTPUT=/tmp/linker_debug ./prog

# The file will be named /tmp/linker_debug.PID (e.g., /tmp/linker_debug.12345)
ls /tmp/linker_debug.*

# Open the file
less /tmp/linker_debug.12345

# Combine multiple keywords with comma separation
LD_DEBUG=libs,symbols,bindings ./prog 2>&1 | head -50

# Real debugging scenario: "undefined symbol" at runtime
# Step 1: check which libraries load
LD_DEBUG=libs ./prog 2>&1 | grep "find library"

# Step 2: check if the symbol exists in the expected library
nm -D /path/to/libfoo.so | grep my_missing_function

# Step 3: check what version your program needs
readelf -d ./prog | grep NEEDED
ldd ./prog

# Step 4: if library is found but symbol isn't, check symbol lookup
LD_DEBUG=symbols ./prog 2>&1 | grep my_missing_function

# Check for unused libraries (helps reduce binary size / load time)
LD_DEBUG=unused ./prog 2>&1

# Output example:
#  12345:   unused DSO: /lib/x86_64-linux-gnu/libm.so.6
# → This means -lm is in your link command but no math functions were called
# → You can remove -lm from your Makefile

Here is a realistic step-by-step workflow for diagnosing a library loading failure:

/* Step 0: The problem — program fails to start */
$ ./prog
./prog: error while loading shared libraries: libfoo.so.1:
        cannot open shared object file: No such file or directory

/* Step 1: Check what libraries the program needs */
$ ldd ./prog
    linux-vdso.so.1 (0x00007ffc...)
    libfoo.so.1 => not found        ← problem here
    libc.so.6 => /lib/x86_64-linux-gnu/libc.so.6

/* Step 2: Find where libfoo.so.1 actually is */
$ find /usr /lib /opt -name "libfoo.so*" 2>/dev/null
/opt/myapp/lib/libfoo.so.1

/* Step 3: See what paths the linker searches */
$ LD_DEBUG=libs ./prog 2>&1 | grep "find library=libfoo"
     find library=libfoo.so.1 [0]; searching
      search cache=/etc/ld.so.cache
      search path=/usr/lib          (from RPATH)
      trying file=/usr/lib/libfoo.so.1  (not found)
      ...

/* Step 4a: Quick fix — add path via LD_LIBRARY_PATH */
$ LD_LIBRARY_PATH=/opt/myapp/lib ./prog

/* Step 4b: Permanent fix — add to ldconfig */
$ echo "/opt/myapp/lib" > /etc/ld.so.conf.d/myapp.conf
$ ldconfig   # rebuilds /etc/ld.so.cache

/* Verify fix */
$ ldd ./prog
    libfoo.so.1 => /opt/myapp/lib/libfoo.so.1  ← now found

This chapter covered four advanced features of Linux shared libraries: