man: leggi il manuale di qualsiasi comando

man mostra la documentazione ufficiale di un comando, di un file di configurazione o di una funzione di sistema, direttamente nel terminale. È il comando che ti permette di imparare tutti gli altri: quando non ricordi un'opzione o vuoi sapere cosa fa esattamente un comando, la risposta è quasi sempre lì.

Cos'è

man è l'abbreviazione di manual, "manuale". È il visualizzatore delle pagine di manuale (man pages), una tradizione dei sistemi Unix che risale agli anni Settanta. Su molte distribuzioni è fornito dal pacchetto man-db, mentre le pagine dei comandi arrivano con i rispettivi pacchetti. Per mostrare il testo usa un pager, di norma less: per questo ci si muove con gli stessi tasti che hai visto nell'articolo dedicato.

Cosa fa

Cerca la pagina di manuale col nome indicato e la apre in lettura. Ogni pagina è organizzata in sezioni fisse, tra cui:

• NAME: il nome e una descrizione di una riga.
• SYNOPSIS: la sintassi del comando.
• DESCRIPTION: cosa fa, nel dettaglio.
• OPTIONS: l'elenco completo delle opzioni.
• EXAMPLES: esempi d'uso, quando ci sono.
• EXIT STATUS, FILES, SEE ALSO: codici di uscita, file coinvolti, comandi collegati.

Non modifica nulla: legge e basta.

Come si usa

Sintassi base:

$ man [sezione] nome

Esempio 1: aprire il manuale di un comando

$ man ls

Si apre la pagina di ls. Ci si muove come in less:

• Spazio / b: pagina avanti / indietro.
• / seguito da un testo e Invio: cerca; n e N passano alla corrispondenza successiva o precedente.
• g / G: inizio / fine.
• h: aiuto sui comandi di navigazione.
• q: esci.

Per trovare un'opzione precisa, cerca il suo nome: per esempio digita /--human-readable e premi Invio.

Esempio 2: capire come leggere la sintassi

La sezione SYNOPSIS usa una notazione precisa. Per cp mostra, tra le altre, queste forme:

cp [OPTION]... [-T] SOURCE DEST
cp [OPTION]... SOURCE... DIRECTORY

• Le parentesi quadre [ ] indicano ciò che è facoltativo.
• I tre puntini ... indicano che l'elemento può essere ripetuto.
• La barra verticale | separa le alternative: l'una o l'altra.
• Le parole scritte in grassetto vanno digitate così come sono; quelle in corsivo (o maiuscolo) sono segnaposto da sostituire.

Esempio 3: le sezioni del manuale

Le pagine sono raggruppate in numeri, detti sezioni:

Alcuni nomi esistono in più sezioni. Per esempio passwd è sia il comando per cambiare la password sia il file che contiene gli utenti. Si sceglie indicando il numero:

$ man passwd        # il comando (sezione 1)
$ man 5 passwd      # il formato del file /etc/passwd

Esempio 4: cercare un comando per argomento con -k

Se non ricordi il nome del comando ma sai a cosa serve, man -k cerca una parola nelle descrizioni di tutte le pagine (equivale al comando apropos):

$ man -k passwd
passwd (1)           - change user password
passwd (5)           - the password file

Con un termine più generico la lista può essere lunga: puoi restringerla con grep:

$ man -k copy | grep -i file

Se la ricerca non restituisce nulla, il database delle descrizioni potrebbe non essere aggiornato: lo si ricostruisce con sudo mandb.

Esempio 5: una descrizione in una riga con -f

$ man -f ls
ls (1)               - list directory contents

È la stessa cosa del comando whatis: mostra solo la riga NAME, senza aprire la pagina.

Esempio 6: l'aiuto breve con --help

Quasi tutti i comandi GNU hanno un'opzione --help che stampa un riassunto molto più corto del manuale:

$ ls --help
$ cp --help | less

Quando ti serve solo ricordare il nome di un'opzione, è più rapido; quando vuoi capire il comportamento nei dettagli, il manuale è la fonte più completa.

Esempio 7: i comandi interni della shell con help

Comandi come cd non sono programmi separati ma fanno parte della shell, e man cd può mostrare la pagina generale di Bash o dirti che non esiste. Per questi comandi si usa help:

$ help cd

Esempio 8: salvare una pagina in un file di testo

$ man ls | col -b > ls_manuale.txt

Il comando col -b toglie i caratteri di formattazione, e il risultato è un file di testo semplice, consultabile con less o stampabile.

Esempio 9: leggere il manuale in inglese

Alcune pagine sono tradotte in italiano (se è installato il pacchetto di traduzione), ma le traduzioni sono spesso incomplete o indietro rispetto alla versione originale. Per leggere la pagina in inglese:

$ LANG=C man ls

Esempio 10: uso negli script

Con -w man stampa il percorso della pagina invece di aprirla, e restituisce un errore se non esiste. Si può usare per verificare che una pagina sia presente:

#!/bin/bash
if man -w rsync > /dev/null 2>&1; then
    echo "Il manuale di rsync è installato"
else
    echo "Manuale non trovato"
fi

Opzioni utili

• man N nome: apre la pagina nella sezione N.
• -k parola (apropos): cerca una parola nelle descrizioni.
• -f nome (whatis): mostra la descrizione di una riga.
• -a nome: mostra tutte le pagine con quel nome, una dopo l'altra.
• -w nome: stampa il percorso del file della pagina.

Attenzione a

• Come si esce: si preme q, come in less.
• Il manuale descrive la versione installata: è un vantaggio, perché le opzioni descritte sono quelle del programma che hai davvero. Ricorda però che comandi con lo stesso nome possono comportarsi diversamente su sistemi diversi (GNU/Linux, macOS, BSD).
• Non tutto ha una pagina: per un comando inesistente o non installato ottieni il messaggio No manual entry for nome (o la sua traduzione). Prova con man -k per scoprire il nome giusto, oppure verifica con type nome se il comando esiste davvero.
• Pagine lunghe e fitte: non serve leggerle dall'inizio alla fine. Parti da SYNOPSIS e dagli EXAMPLES, poi cerca l'opzione che ti interessa con /.
• Alternative: alcuni programmi GNU hanno una documentazione più estesa consultabile con info nome. Esistono anche progetti come tldr, che offrono riassunti con esempi pratici, ma non sono installati di serie.

Riepilogo