Comando whatis in Linux: leggere descrizioni e sezioni dei manuali

whatis mostra una breve descrizione delle pagine di manuale il cui nome corrisponde a quello cercato. Usatelo quando conoscete già il nome di un comando e volete ricordarne la funzione o vedere in quali sezioni è documentato.

Questa guida riguarda man-db, l’insieme di strumenti per consultare i manuali usato da molte distribuzioni Linux. whatis cerca per impostazione predefinita il nome esatto; anche man -f offre la descrizione breve. Per cercare invece parole contenute nella descrizione, usate apropos. Potete poi aprire la pagina completa con il comando man.

Che cos’è il comando whatis?

La sezione NAME contiene il nome della pagina e una breve descrizione. whatis consulta il database indicizzato di man-db e mostra le descrizioni associate ai nomi corrispondenti, senza aprire tutto il manuale.

La descrizione serve a riconoscere rapidamente una funzione. Non indica quale eseguibile verrà avviato dalla shell: alias, funzioni e comandi builtin possono avere lo stesso nome di un programma documentato.

Sintassi di base e lettura dell'output

whatis [option] name...

[option] rappresenta opzioni facoltative e name... uno o più nomi: sostituite questi segnaposto senza digitare le parentesi o i puntini.

Per leggere la descrizione di ls, indicate il suo nome:

whatis ls

Un risultato può avere questo formato. È un esempio illustrativo con descrizione inglese, non un output garantito su ogni sistema:

ls (1)               - list directory contents

ls è il nome della pagina, (1) è la sezione e il testo dopo il trattino ne riassume la funzione. Lingua, descrizione e disponibilità dipendono dai manuali installati. Per leggere sintassi e opzioni, aprite la pagina completa; dal pager abituale si esce con q.

man 1 ls

Controllare più nomi contemporaneamente

Passate più nomi come argomenti separati per ottenere le relative descrizioni:

whatis ls cp mv rm

È un modo rapido per confrontare comandi noti. Un’esecuzione con più nomi può però stampare risultati anche se alcune pagine mancano: non considerate la presenza di output come prova che ogni nome sia stato trovato. In uno script che deve verificare ciascuna pagina, cercate un nome alla volta e controllatene lo stato, come nell’esempio più avanti.

Quando lo stesso nome appare in più sezioni

Un nome può appartenere a pagine di sezioni diverse, producendo più righe. Per esempio, passwd può identificare sia il comando per gestire la password sia il formato del file degli account, se entrambi i manuali sono installati.

whatis passwd

Se compaiono passwd(1) e passwd(5), scegliete la pagina specificando la sezione:

man 1 passwd
man 5 passwd

Il valore tra parentesi è una sezione del manuale, non la versione del programma. La sezione 1 riguarda i comandi per utenti, la 8 quelli di amministrazione e la 5 i formati dei file.

Cercare nomi con espressioni regolari e caratteri jolly

Ricerca con espressioni regolari: -r

-r, o --regex, interpreta il termine come espressione regolare e cerca una corrispondenza anche in una parte del nome della pagina, non nella sua descrizione.

whatis -r '^ssh'
whatis --regex 'printf$'

Il primo esempio cerca nomi che iniziano con ssh; il secondo nomi che terminano con printf. Gli apici impediscono alla shell di interpretare prima i caratteri speciali, ma non disattivano l’espressione regolare elaborata da whatis.

Ricerca con caratteri jolly: -w

-w, o --wildcard, usa pattern con i caratteri jolly della shell. Il pattern deve corrispondere all’intero nome della pagina: ssh* seleziona nomi che iniziano con ssh, mentre *printf* include quelli che contengono printf.

whatis -w 'ssh*'
whatis --wildcard '*printf*'

Mantenete gli apici: senza questa protezione, la shell potrebbe espandere * nei nomi dei file della directory corrente prima di eseguire whatis. Le modalità -r e -w possono essere più lente della ricerca normale nell’indice.

Limitare la ricerca alle sezioni

-s, o --sections, limita la ricerca alle sezioni richieste. Le prime due righe separano il comando passwd dal formato del file; l’ultima cerca printf nelle sezioni 2 e 3, mostrando soltanto le corrispondenze installate.

whatis -s 1 passwd
whatis -s 5 passwd
whatis --sections=2,3 printf

In man-db una sezione semplice come 3 include anche sottosezioni come 3perl e 3x. Un valore completo, per esempio 3perl, limita invece la ricerca a quella sottosezione.

Opzioni utili di whatis

Relazione tra whatis e man -f

Con man-db, man -f permette di trovare la descrizione breve di un nome, in modo analogo a whatis:

whatis printf
man -f printf

Scegliete la forma che ricordate meglio. In entrambi i casi ottenete una descrizione breve; per leggere il manuale completo usate man NOME, eventualmente precedendo il nome con la sezione.

Differenze tra whatis, apropos e type

Un risultato di whatis non dimostra che un eseguibile con quel nome sia nel PATH corrente. Vale anche il contrario: un programma può essere disponibile senza la relativa pagina di manuale installata.

Risoluzione dei problemi quando non ci sono risultati di ricerca

Verificare il nome della pagina e lo stato dell'installazione

Controllate di avere usato il nome della pagina, non una funzione descritta al suo interno. Nell’esempio, apropos cerca manuali sull’archiviazione, command -v controlla come la shell risolve tar e whatis ne cerca la descrizione. I tre risultati rispondono a domande diverse.

apropos archive
command -v tar
whatis tar

Controllare e aggiornare l’indice

Se le pagine pertinenti sono installate ma non vengono trovate dopo una nuova installazione, l’indice potrebbe essere assente o non aggiornato. Un amministratore può crearlo o aggiornarlo con:

sudo mandb

mandb scrive nell’indice dei manuali di sistema e può richiedere privilegi amministrativi. Molte distribuzioni lo avviano automaticamente durante l’installazione dei pacchetti o con attività pianificate: non serve eseguirlo ripetutamente senza motivo. Un aggiornamento non installa manuali mancanti; se non avete i permessi necessari, controllate prima percorsi e impostazioni della distribuzione.

Controllare la locale e MANPATH

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

locale mostra le impostazioni linguistiche; manpath mostra i percorsi calcolati per i manuali, mentre printf legge soltanto la variabile MANPATH. Se questa è vuota o non impostata, man-db può ricavare i percorsi dal PATH: un valore vuoto non significa assenza di manuali. Un valore personalizzato può invece escludere gerarchie utili. Le descrizioni tradotte devono essere installate perché possano comparire nella lingua desiderata.

Controllare la documentazione con uno script Bash

Per un controllo automatico usate lo stato di uscita, evitando di analizzare descrizioni che cambiano con lingua e versione. In man-db 0 indica successo, 1 un errore d’uso, sintassi o configurazione, 2 un errore operativo e 16 l’assenza di corrispondenze. Altre implementazioni possono differire: consultate man whatis sul sistema interessato.

Salvate il codice completo in verifica-manuale.sh. Su un sistema con Bash, man-db e i manuali installati, eseguite bash verifica-manuale.sh ls, passando un solo nome non vuoto. Lo script conserva i messaggi diagnostici di whatis e il suo stato di uscita.

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

if whatis "$1" >/dev/null; then
  printf '%s\n' 'Descrizione del manuale trovata.'
  exit 0
else
  status=$?
  if [ "$status" -eq 16 ]; then
    printf '%s\n' 'Nessuna descrizione corrispondente.' >&2
  else
    printf 'Errore nella ricerca: stato=%d\n' "$status" >&2
  fi
  exit "$status"
fi

Se la descrizione esiste, vedrete il messaggio di successo con stato 0. In assenza di corrispondenze, il messaggio andrà allo standard error e lo stato sarà 16. Subito dopo lo script, echo "$?" mostra il valore restituito. Il controllo degli argomenti dello script usa anch’esso lo stato 2. Questi esiti riguardano la documentazione, non la disponibilità dell’eseguibile.

Domande frequenti

whatis mostra il percorso effettivo di un comando?

No. Mostra nomi e descrizioni delle pagine di manuale. Per sapere come la shell risolve un comando, usate type o command -v; il risultato può essere anche un alias, una funzione o un builtin.

Come posso cercare usando parole incluse nella descrizione?

Usate apropos PAROLA_CHIAVE oppure man -k PAROLA_CHIAVE. whatis è adatto quando conoscete il nome della pagina; anche con -r o -w cerca nei nomi, non nel testo delle descrizioni.

Perché lo stesso nome viene stampato su più righe?

Possono essere installate pagine omonime in sezioni diverse. Controllate il numero tra parentesi e aprite quella desiderata con man SEZIONE NOME, ad esempio man 5 passwd per il formato del file.

Scegliere lo strumento adatto

Usate whatis NOME per riconoscere una pagina già nota e scegliere la sezione corretta prima di aprirla con man. Se non compare una voce attesa, verificate nome, documentazione installata, percorsi e indice.

Per una ricerca per argomento passate ad apropos. Per verificare ciò che la shell eseguirà, scegliete type o command -v: la disponibilità di un programma e quella della sua documentazione vanno controllate separatamente.

Documentazione di riferimento

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