1. Three Names Every Shared Library Has

Before we understand ldconfig, we must understand the three names a shared library uses. Each serves a different purpose.

2. What ldconfig Does — Two Main Tasks

When you run ldconfig (usually as root), it performs exactly two tasks:

Code Example 1 — Build a Shared Library and Run ldconfig

This full example walks through building a shared library with a soname, installing it, and running ldconfig to register it.

Step 1: Write the library source files

/* mod1.c — first module of our shared library */
#include <stdio.h>

void hello_from_mod1(void) {
    printf("Hello from mod1! (libdemo version 1.0.1)\n");
}

int add_numbers(int a, int b) {
    return a + b;
}

/* mod2.c — second module */
#include <stdio.h>

void hello_from_mod2(void) {
    printf("Hello from mod2! (libdemo version 1.0.1)\n");
}

/* demo.h — public header */
#ifndef DEMO_H
#define DEMO_H

void hello_from_mod1(void);
void hello_from_mod2(void);
int  add_numbers(int a, int b);

#endif

Step 2: Compile with -fPIC

# Compile each source file to Position Independent Code (PIC)
# -fPIC is REQUIRED for shared library code
# -g adds debug info, -Wall enables warnings

gcc -g -c -fPIC -Wall mod1.c mod2.c

Step 3: Link into a shared library with soname

# -shared: create a shared library (DSO)
# -Wl,-soname,libdemo.so.1 : embed soname "libdemo.so.1" inside the ELF file
# -o libdemo.so.1.0.1      : output file = real name

gcc -g -shared -Wl,-soname,libdemo.so.1 \
    -o libdemo.so.1.0.1 \
    mod1.o mod2.o

Step 4: Verify the embedded soname

# readelf shows the ELF dynamic section
# grep for SONAME entry

readelf -d libdemo.so.1.0.1 | grep SONAME

# Expected output:
# 0x000000000000000e (SONAME) Library soname: [libdemo.so.1]

Step 5: Install and run ldconfig

# Copy real file to /usr/local/lib
sudo cp libdemo.so.1.0.1 /usr/local/lib/

# Make sure /usr/local/lib is in /etc/ld.so.conf.d/
echo "/usr/local/lib" | sudo tee /etc/ld.so.conf.d/local.conf

# Run ldconfig (creates cache + soname symlink automatically)
sudo ldconfig -v | grep libdemo

# Expected output:
#   libdemo.so.1 -> libdemo.so.1.0.1

# Verify symlink was created
ls -l /usr/local/lib/libdemo*
# lrwxrwxrwx libdemo.so.1 -> libdemo.so.1.0.1
# -rwxr-xr-x libdemo.so.1.0.1

# Manually create linker name (ldconfig does NOT do this)
sudo ln -s libdemo.so.1 /usr/local/lib/libdemo.so

Step 6: Compile and run a test program

/* main.c — test program that uses libdemo */
#include "demo.h"
#include <stdio.h>

int main(void) {
    hello_from_mod1();
    hello_from_mod2();
    printf("3 + 4 = %d\n", add_numbers(3, 4));
    return 0;
}

# -ldemo tells linker to find libdemo.so (linker name)
# -L/usr/local/lib tells the compiler where to find it

gcc -o demo_prog main.c -ldemo -L/usr/local/lib

# Run the program
./demo_prog
# Hello from mod1! (libdemo version 1.0.1)
# Hello from mod2! (libdemo version 1.0.1)
# 3 + 4 = 7

3. ldconfig Command-Line Options

Code Example 2 — Two Major Versions Side by Side

This example installs libdemo.so.1.0.1 and libdemo.so.2.0.0 simultaneously and shows how ldconfig creates separate soname symlinks for each.

# Suppose we already have libdemo.so.1.0.1 in /usr/lib
# Now we build a new MAJOR version (breaking change)

gcc -g -c -fPIC -Wall mod1_v2.c mod2_v2.c

# Note: soname now says libdemo.so.2
gcc -g -shared -Wl,-soname,libdemo.so.2 \
    -o libdemo.so.2.0.0 \
    mod1_v2.o mod2_v2.o

# Install both versions
sudo mv libdemo.so.1.0.1 libdemo.so.2.0.0 /usr/lib/

# Run ldconfig — it finds BOTH and creates BOTH soname symlinks
sudo ldconfig -v | grep libdemo
#   libdemo.so.1 -> libdemo.so.1.0.1  (changed)
#   libdemo.so.2 -> libdemo.so.2.0.0  (changed)

# Verify in /usr/lib
ls -l /usr/lib/libdemo*
# lrwxrwxrwx libdemo.so.1 -> libdemo.so.1.0.1
# -rwxr-xr-x libdemo.so.1.0.1
# lrwxrwxrwx libdemo.so.2 -> libdemo.so.2.0.0
# -rwxr-xr-x libdemo.so.2.0.0

# Create the linker name pointing to the NEW version
sudo ln -s libdemo.so.2 /usr/lib/libdemo.so

# New programs compiled with -ldemo will link against v2
# Old programs that embedded soname "libdemo.so.1" still
# find libdemo.so.1 -> libdemo.so.1.0.1 and work fine!

Code Example 3 — Private Library with ldconfig -n

When you are developing a private library (not installed in a system directory), you can still use ldconfig to create soname symlinks automatically using the -n option.

/* Build and use a private library in current directory */

# Step 1: Compile modules
gcc -g -c -fPIC -Wall mod1.c mod2.c

# Step 2: Create shared library with soname
gcc -g -shared -Wl,-soname,libdemo.so.1 \
    -o libdemo.so.1.0.1 \
    mod1.o mod2.o

# Step 3: Use ldconfig -n to create soname symlink only in this dir
# -n: process only libs in specified directory
# -v: verbose
/sbin/ldconfig -nv .

# Output:
# .:
#   libdemo.so.1 -> libdemo.so.1.0.1

# Check result
ls -l libdemo.so*
# lrwxrwxrwx libdemo.so.1 -> libdemo.so.1.0.1
# -rwxr-xr-x libdemo.so.1.0.1

# Step 4: Manually create linker name
ln -s libdemo.so.1 libdemo.so

# Step 5: Compile test program, using current dir as lib search path
gcc -o demo_prog main.c -ldemo -L.

# Step 6: Tell dynamic linker to find our library in current dir
export LD_LIBRARY_PATH=.
./demo_prog

# Output:
# Hello from mod1!
# Hello from mod2!

4. LD_LIBRARY_PATH — Runtime Library Search Path

The dynamic linker (ld.so or ld-linux.so) searches for shared libraries at run time in this order:

# Check what library a program needs
ldd ./demo_prog
# linux-vdso.so.1 (0x00007fff...)
# libdemo.so.1 => /usr/local/lib/libdemo.so.1.0.1 (0x00007f...)
# libc.so.6 => /lib/x86_64-linux-gnu/libc.so.6 (0x00007f...)

# View cache contents
ldconfig -p | grep libdemo
# libdemo.so.1 (libc6,x86-64) => /usr/local/lib/libdemo.so.1.0.1

Interview Questions & Answers