Salta al contenuto principale

ldconfig: gestire la cache delle librerie condivise

Inviato da tuxsa il

Hai installato una libreria a mano, magari compilata dai sorgenti in /opt o /usr/local, ma il programma che la usa risponde ancora cannot open shared object file. Il file c'è, eppure il sistema non lo trova. Di solito manca un passaggio: ldconfig.

Cos'è

ldconfig è il comando che prepara le librerie condivise (i file .so) perché il sistema le trovi in fretta. Legge l'elenco delle cartelle in cui cercare, esamina le librerie che contengono e costruisce un indice, la cache /etc/ld.so.cache. All'avvio di ogni programma il loader consulta quel file invece di scorrere le cartelle una per una.

Fa parte della libreria C di sistema (glibc), quindi è già presente su Debian e Ubuntu. Dopo le installazioni con apt viene eseguito automaticamente dai pacchetti che ne hanno bisogno: lo si lancia a mano quando si aggiungono librerie fuori dal gestore dei pacchetti.

Cosa fa

Quando lo si esegue, ldconfig fa due cose:

  • ricostruisce /etc/ld.so.cache a partire dalle cartelle elencate in /etc/ld.so.conf e nei file /etc/ld.so.conf.d/*.conf, più le cartelle di sistema (/lib e /usr/lib);
  • crea o aggiorna i collegamenti simbolici (symlink) col nome corto della libreria, ricavato dall'soname scritto dentro al file. Ad esempio da libmio.so.1.0 ricava libmio.so.1.

Le cartelle standard da cui parte sono scritte nei file di configurazione. Nel mio test su Ubuntu 24.04 /etc/ld.so.conf contiene solo include /etc/ld.so.conf.d/*.conf e in /etc/ld.so.conf.d/ ci sono libc.conf (con /usr/local/lib) e x86_64-linux-gnu.conf (con le cartelle /lib/x86_64-linux-gnu e /usr/lib/x86_64-linux-gnu).

Come si usa

$ ldconfig [opzioni] [cartella...]

Per ricostruire la cache servono i privilegi di root (sudo); per consultarla con -p no. Gli output sono quelli reali del mio test (glibc 2.39). I messaggi possono essere tradotti su un sistema con locale italiano.

Esempio 1: consultare la cache

$ ldconfig -p | head -3 | cut -c1-80
859 libs found in cache `/etc/ld.so.cache'
    libzzipwrap-0.so.13 (libc6,x86-64) => /lib/x86_64-linux-gnu/libzzipwrap-0.so.13
    libzzipmmapped-0.so.13 (libc6,x86-64) => /lib/x86_64-linux-gnu/libzzipmmapped-0.s...

$ ldconfig -p | grep 'libc.so.6'
    libc.so.6 (libc6,x86-64) => /lib/x86_64-linux-gnu/libc.so.6

-p (print cache) stampa il contenuto della cache: nome della libreria, architettura e file reale. Il numero di librerie (qui 859) dipende da cosa è installato; ho accorciato alcune righe con cut. Con grep si risponde a "il sistema vede questa libreria? e da quale file?". Se non compare, per il loader non esiste, anche se il file è sul disco.

Esempio 2: far trovare una libreria in una cartella nuova

$ ./prog
./prog: error while loading shared libraries: libmio.so.1: cannot open shared
object file: No such file or directory

$ echo "/opt/miolib/lib" | sudo tee /etc/ld.so.conf.d/mio.conf
$ sudo ldconfig
$ ldconfig -p | grep mio
    libmio.so.1 (libc6,x86-64) => /opt/miolib/lib/libmio.so.1
$ ./prog
42

È il caso d'uso principale. Si crea un file .conf in /etc/ld.so.conf.d/ con il percorso della cartella (qui /opt/miolib/lib è un nome illustrativo: nel mio test la cartella era sotto /tmp e la libreria era compilata da me), si esegue sudo ldconfig e il programma parte. Ho spezzato io il messaggio di errore su due righe. Rispetto a LD_LIBRARY_PATH (di cui parla l'articolo su ldd) la soluzione è permanente e vale per tutti gli utenti e programmi.

Esempio 3: cosa ha fatto ldconfig

$ sudo ldconfig -v 2>/dev/null | grep -A1 '^/opt/miolib/lib'
/opt/miolib/lib: (from /etc/ld.so.conf.d/mio.conf:1)
    libmio.so.1 -> libmio.so.1.0

$ ls -l /opt/miolib/lib
libmio.so -> libmio.so.1.0
libmio.so.1 -> libmio.so.1.0
libmio.so.1.0

Con -v (verbose) ldconfig elenca le cartelle esaminate, indicando da quale file di configurazione provengono, e i collegamenti creati. Qui ha creato il link libmio.so.1, che è proprio il nome richiesto dal programma. Nel mio test libmio.so l'avevo già creato io per la compilazione; ldconfig si occupa dei nomi legati all'soname. L'output completo è molto lungo perché include tutte le cartelle di sistema, per questo ho filtrato con grep.

Esempio 4: aggiornare solo i collegamenti o solo la cache

$ sudo ldconfig -N     # solo i symlink, la cache non viene ricostruita
$ ldconfig -p | grep -c libnuova
0
$ sudo ldconfig -X     # solo la cache, i symlink non vengono toccati
$ ldconfig -p | grep libnuova
    libnuova.so.3 (libc6,x86-64) => /opt/miolib/lib/libnuova.so.3

-N (no cache) salta la ricostruzione della cache, -X salta l'aggiornamento dei symlink. Li ho provati con una libreria appena copiata nella cartella: dopo -N non risultava nella cache, dopo -X sì. Nell'uso di tutti i giorni basta sudo ldconfig senza opzioni.

Esempio 5: senza permessi

$ ldconfig
/sbin/ldconfig.real: Can't create temporary cache file /etc/ld.so.cache~: Permission
denied
$ echo $?
1

Da utente normale la ricostruzione fallisce con codice 1, perché non si può scrivere in /etc. Nel mio test ho usato l'utente nobody. Il nome ldconfig.real è specifico di Ubuntu, dove ldconfig è un piccolo programma che chiama quello vero; su altre distribuzioni il messaggio può differire. Il messaggio è su una riga sola, l'ho spezzato per la pagina. ldconfig -p, invece, funziona anche senza privilegi.

Esempio 6: uso negli script

#!/bin/bash
# Dice quale file la cache di ldconfig usa per una libreria (es. libssl)
[ $# -eq 1 ] || { echo "Uso: $0 nome-libreria" >&2; exit 2; }
command -v ldconfig >/dev/null || { echo "ldconfig non trovato" >&2; exit 3; }
res=$(ldconfig -p | awk -v n="$1" 'index($1, n) == 1 {print $1, $NF}')
if [ -z "$res" ]; then
    echo "$1: non presente nella cache (provare: sudo ldconfig)" >&2
    exit 1
fi
echo "$res"

Lo script cerca nella cache le librerie il cui nome inizia con la stringa data e stampa nome e file reale; esce con 1 se non ne trova, 2 senza argomenti e 3 se ldconfig non c'è. Con ./chk.sh libc.so stampa libc.so.6 /lib/x86_64-linux-gnu/libc.so.6. Su una libreria inesistente esce con 1 e suggerisce di eseguire sudo ldconfig. Nei miei test ha funzionato in tutti questi casi. In caso di nome ambiguo possono comparire più righe.

Opzioni utili

  • -p: stampa il contenuto della cache (non richiede root).
  • -v: mostra cartelle e collegamenti elaborati.
  • -N: non ricostruisce la cache; -X: non aggiorna i symlink.
  • -n cartella: elabora solo la cartella indicata (crea i symlink) senza toccare la cache. Non l'ho provata isolatamente.
  • -C file: usa un file di cache diverso da /etc/ld.so.cache.
  • -f file: usa un file di configurazione diverso da /etc/ld.so.conf. Con -C e -f insieme si possono fare prove senza toccare la cache di sistema: nel mio test ha prodotto una cache separata con 856 librerie.
  • -r radice: lavora in un altro filesystem radice (chroot). Non l'ho provata.

Attenzione a

  • Dopo aver aggiunto una libreria a mano, serve sudo ldconfig. Il file nella cartella non basta: finché la cache non viene ricostruita il loader non lo vede. Nel mio test, dopo la rimozione della configurazione e un nuovo ldconfig, il programma è tornato a fallire.
  • La cartella deve essere elencata in un file di configurazione. Se la libreria è in una cartella non standard e non c'è un file .conf corrispondente, ldconfig la ignora.
  • Il nome è quello dell'soname, non del file. ldconfig classifica le librerie in base al nome scritto dentro al file. Nel mio test una copia rinominata di una libreria, con un soname diverso dal nome del file, non è comparsa nella cache col nuovo nome.
  • Non sostituisce LD_LIBRARY_PATH in ogni caso. Per una prova veloce, senza modificare il sistema, la variabile è più comoda e si limita a un comando. La modifica permanente è quella con ldconfig.
  • Attenzione alle librerie di sistema. Aggiungere una cartella con una versione diversa di una libreria già installata può far usare la versione sbagliata ad altri programmi. Il consiglio è dare alla cartella un nome ben distinto e controllare con ldconfig -p | grep nome cosa risulta. Questo è un consiglio generale, non un caso che ho riprodotto.
  • Un errore nel file .conf influenza tutto il sistema. Conviene non lasciare file di prova in /etc/ld.so.conf.d/: ogni cartella elencata viene esaminata a ogni esecuzione di ldconfig.

Riepilogo

ComandoCosa fa
sudo ldconfigRicostruisce la cache e aggiorna i symlink
ldconfig -pMostra il contenuto della cache
ldconfig -p | grep nomeCerca una libreria nella cache
sudo ldconfig -vRicostruisce la cache mostrando cosa elabora
sudo ldconfig -NAggiorna solo i symlink, non la cache
sudo ldconfig -XAggiorna solo la cache, non i symlink
sudo tee /etc/ld.so.conf.d/x.confAggiunge una cartella di ricerca (poi ldconfig)