Comando apropos in Linux: cercare manuali per descrizione

apropos cerca parole chiave nei nomi e nelle descrizioni di una riga delle pagine di manuale. È utile quando conoscete l’operazione da svolgere, come comprimere file o gestire utenti, ma non il nome del comando da cercare.

Questa guida riguarda l’implementazione man-db, usata da molte distribuzioni Linux. Il comando man offre la stessa ricerca con man -k. Per restringere i risultati, potete combinare parole, scegliere sezioni e distinguere espressioni regolari da caratteri jolly.

Che cos’è apropos e dove cerca?

Le pagine di manuale contengono un nome e una breve descrizione delle loro funzioni. apropos consulta queste informazioni nel database indicizzato di man-db e restituisce le voci corrispondenti.

La ricerca non esamina tutto il corpo dei manuali: una pagina pertinente può non comparire se la parola manca sia nel nome sia nella descrizione. Inoltre, i risultati dipendono dai manuali installati e dall’aggiornamento dell’indice.

Sintassi di base e lettura dei risultati

apropos [option] keyword...

[option] indica opzioni facoltative e keyword... una o più parole chiave: sostituite questi segnaposto con i valori desiderati, senza digitare le parentesi o i puntini.

Nei comandi seguenti usate parole inglesi se le descrizioni installate sono in inglese. Per cercare le voci relative alla copia di file, provate:

apropos copy

Ecco un esempio illustrativo del formato dei risultati; le righe effettive e la lingua delle descrizioni dipendono dai manuali installati:

cp (1)               - copy files and directories
scp (1)              - OpenSSH secure file copy

Il primo campo è il nome della pagina, il valore tra parentesi è la sezione e il testo dopo il trattino è la descrizione. Quando trovate la voce desiderata, apritela con man specificando la sezione; per uscire dal pager abituale premete q.

man 1 cp
man 1 scp

Metodi di ricerca con più parole chiave

Ricerca predefinita: basta una corrispondenza

Con più parole chiave, la ricerca predefinita usa una condizione OR: basta che una delle espressioni corrisponda al nome o alla descrizione. L’esempio seguente include quindi voci relative a network oppure ad address.

apropos network address

Richiedere tutte le parole con -a

-a, equivalente a --and, richiede invece che ogni parola chiave trovi una corrispondenza nella voce. Le parole non devono necessariamente essere consecutive né nello stesso ordine.

apropos -a network address
apropos --and user password

Gli apici raggruppano una frase in un solo argomento e impediscono alla shell di espandere i caratteri speciali. Non disattivano però le espressioni regolari interpretate da apropos: un punto o un asterisco conservano il loro significato nella ricerca predefinita.

Espressioni regolari, ricerche esatte e caratteri jolly

Ricerca predefinita con espressioni regolari

In man-db la modalità predefinita è -r, cioè una ricerca tramite espressioni regolari estese. Ogni espressione viene confrontata separatamente con il nome e con la descrizione, anche all’interno di una parola. Se volete cercare letteralmente caratteri come il punto, dovete proteggerli anche dall’interpretazione dell’espressione regolare.

apropos '^ssh'
apropos 'file.*system'

^ssh cerca un nome o una descrizione che inizi con ssh, non una parola qualsiasi che inizi così nel mezzo della descrizione. In file.*system, .* ammette zero o più caratteri: può quindi corrispondere sia a filesystem sia a file system.

Cercare una parola chiave esatta con -e

-e, o --exact, seleziona la ricerca della parola chiave esatta nei nomi e nelle descrizioni, invece di trattarla come espressione regolare. Se conoscete già il nome della pagina e vi serve soltanto la sua descrizione, potete usare whatis.

apropos -e printf

Usare i caratteri jolly con -w

-w, o --wildcard, interpreta il termine come un pattern con caratteri jolly della shell. Proteggete il pattern con gli apici per evitare che la shell lo sostituisca prima con i nomi dei file. Senza -e, man-db ammette anche corrispondenze ai confini delle parole nella descrizione; combinando -w -e, il pattern deve coprire l’intero nome o l’intera descrizione.

apropos -w 'ssh*'
apropos --wildcard '*password*'

Limitare la ricerca alle sezioni

-s, o --sections, limita la ricerca alle sezioni indicate. Per esempio, -s 1 cerca programmi per utenti, mentre -s 2,3 limita i risultati a chiamate di sistema e funzioni di libreria.

apropos -s 1 archive
apropos -s 2,3 socket
apropos --sections=5 password

Separate le sezioni con virgole o due punti. In man-db -s 3 include anche sottosezioni come 3perl e 3x, se presenti; una sezione completa come -s 3perl seleziona invece soltanto quella sottosezione.

Opzioni di apropos più utili

Qual è la relazione tra apropos e man -k?

In man-db man -k equivale ad apropos e ne usa le opzioni di ricerca. Questi comandi cercano quindi lo stesso termine nelle informazioni indicizzate:

apropos filesystem
man -k filesystem

Scegliete la forma che ricordate meglio. In entrambi i casi state cercando voci di manuale, non verificando se un eseguibile è presente nel percorso di ricerca della shell.

Cosa controllare se non compaiono risultati

Provare parole più generiche

Provate parole più generiche e una sola condizione alla volta. Se sono installate soltanto descrizioni inglesi, una parola italiana può non trovare nulla; usate termini come quelli degli esempi e aggiungete -a solo dopo aver visto i primi risultati.

apropos compress
apropos archive
apropos -a user account

Controllare e aggiornare l’indice

Controllate prima che siano installate le pagine di manuale pertinenti. Se ci sono ma l’indice è assente o non aggiornato dopo l’installazione, un amministratore può aggiornarlo con il comando seguente:

sudo mandb

mandb crea o aggiorna la cache dell’indice e scrive nei database di sistema: eseguitelo con i privilegi necessari solo quando serve. Molte distribuzioni lo avviano già durante l’installazione dei pacchetti o con attività periodiche. Non può aggiungere manuali che non sono installati; eventuali avvisi possono indicare pagine non analizzabili.

Verificare percorsi e impostazioni linguistiche

manpath
printf '%s\n' "$MANPATH"
locale

manpath mostra i percorsi calcolati per i manuali; printf mostra soltanto il valore della variabile MANPATH. Una variabile vuota non significa che manchino i percorsi: man-db può calcolarli a partire da PATH. Un valore personalizzato può invece escludere gerarchie utili. Per una ricerca temporanea, -M accetta percorsi separati da due punti e prevale su MANPATH. locale mostra le impostazioni linguistiche; -L cambia la locale della ricerca, ma non quella dei messaggi iniziali di aiuto.

Usare apropos in uno script Bash

In man-db gli stati di uscita sono 0 per un’esecuzione riuscita, 1 per errori d’uso, sintassi o configurazione, 2 per errori operativi e 16 quando nessuna voce soddisfa i criteri. Non basta controllare se l’output è vuoto: un errore e una ricerca senza risultati richiedono decisioni diverse.

Salvate l’esempio completo seguente in cerca-manuale.sh ed eseguitelo con bash cerca-manuale.sh printf su un sistema con Bash, man-db e i manuali desiderati installati. Passate una sola parola o frase non vuota; racchiudete una frase tra apici. Lo script stampa un messaggio e conserva lo stato restituito da apropos.

if [ "$#" -ne 1 ] || [ -z "$1" ]; then
  printf '%s\n' 'Uso: bash cerca-manuale.sh PAROLA_CHIAVE' >&2
  exit 2
fi

if apropos -e "$1" >/dev/null; then
  printf '%s\n' 'Sono presenti voci di manuale corrispondenti.'
  exit 0
else
  status=$?
  case "$status" in
    16) printf '%s\n' 'Nessuna voce di manuale corrispondente.' >&2 ;;
    *) printf 'Ricerca non riuscita: stato=%d\n' "$status" >&2 ;;
  esac
  exit "$status"
fi

Se esiste una voce corrispondente, vedrete il messaggio di successo e lo stato sarà 0. Se non ce ne sono, il messaggio andrà allo standard error e lo stato sarà 16. Dopo lo script, echo "$?" mostra lo stato appena ricevuto. Gli errori mantengono anche i messaggi diagnostici di apropos. Lo stato 2 è usato inoltre dal controllo degli argomenti dello script. Altre implementazioni possono usare opzioni o stati diversi: controllate man apropos sul sistema interessato.

Confronto con altri comandi

Domande frequenti

Posso cercare con parole italiane?

Sì, se sono installate le descrizioni italiane e la locale della ricerca le seleziona. Se avete soltanto descrizioni inglesi, provate parole inglesi. Cambiare la locale non traduce le pagine mancanti.

Cosa succede se il termine di ricerca contiene spazi?

Racchiudete la frase tra apici per passarla come un unico argomento. Rimane comunque un’espressione regolare nella modalità predefinita. Per cercare invece più parole indipendenti tutte presenti nella voce, passatele separatamente e aggiungete -a.

Dovrei usare apropos invece di which?

Servono a scopi diversi. apropos trova pagine di manuale per argomento; command -v o type mostrano come la shell risolve un nome, anche come alias, funzione o builtin. Una voce di manuale non dimostra da sola che il comando sia disponibile nella shell corrente.

Dalla ricerca alla lettura del manuale

Partite da una parola presente nella descrizione, aggiungete -a per richiedere più condizioni e usate -s per scegliere il tipo di manuale. Se non ottenete risultati, controllate lingua, documentazione installata, percorsi e indice prima di concludere che non esista un comando adatto.

Quando trovate una voce utile, apritela con man e il suo numero di sezione: potrete leggere sintassi, opzioni, condizioni e limiti del comando prima di utilizzarlo.

Documentazione di riferimento

• apropos(1) pagina del manuale
• mandb(8) pagina del manuale
• progetto man-db