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.cachea partire dalle cartelle elencate in/etc/ld.so.confe nei file/etc/ld.so.conf.d/*.conf, più le cartelle di sistema (/libe/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.0ricavalibmio.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.0Con -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 $?
1Da 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-Ce-finsieme 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 nuovoldconfig, 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
.confcorrispondente,ldconfigla ignora. - Il nome è quello dell'soname, non del file.
ldconfigclassifica 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_PATHin ogni caso. Per una prova veloce, senza modificare il sistema, la variabile è più comoda e si limita a un comando. La modifica permanente è quella conldconfig. - 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 nomecosa risulta. Questo è un consiglio generale, non un caso che ho riprodotto. - Un errore nel file
.confinfluenza tutto il sistema. Conviene non lasciare file di prova in/etc/ld.so.conf.d/: ogni cartella elencata viene esaminata a ogni esecuzione dildconfig.
Riepilogo
| Comando | Cosa fa |
|---|---|
sudo ldconfig | Ricostruisce la cache e aggiorna i symlink |
ldconfig -p | Mostra il contenuto della cache |
ldconfig -p | grep nome | Cerca una libreria nella cache |
sudo ldconfig -v | Ricostruisce la cache mostrando cosa elabora |
sudo ldconfig -N | Aggiorna solo i symlink, non la cache |
sudo ldconfig -X | Aggiorna solo la cache, non i symlink |
sudo tee /etc/ld.so.conf.d/x.conf | Aggiunge una cartella di ricerca (poi ldconfig) |