man(1)

NOME
man - formatta e mostra le pagine di manuale

SINTASSI
man [-acdfFhkKtwW] [--path] [-m sistema] [-p stringa] [-C config_file] [-M lista_percorsi] [-P impaginatore] [-B browser] [-H impaginatorehtml] [-S lista_sezione] [sezione] nome ...

DESCRIZIONE
man formatta e mostra le pagine di manuale. Se si specifica sezione man cerca solo in quella sezione del manuale. nome normalmente è il nome della pagina di manuale, che è tipicamente il nome di un comando, funzione, o file. Tuttavia, se name contiene uno slash (/) allora man lo interpreta come la specificazione di un file, quindi si può fare man ./foo.5 o anche man /cd/foo/bar.1.gz.

Vedere più avanti per una descrizione di dove man cerca i file delle pagine di manuale.

OPZIONI

-C  file_configurazione
    Specifica il file di configurazione da usare; il valore predefinito è /etc/man.conf (vedere man.conf(5)).

-M  percorso
    Specifica la lista di directory in cui cercare le pagine di manuale. Separare le directory con caratteri ":". Una lista vuota è come non specificare -M vedere PERCORSO DI RICERCA DELLE PAGINE DI MANUALE.

-P  impaginatore
    Specifica il programma di impaginazione da usare. Questa opzione sovrascrive la variabile d'ambiente MANPAGER, che sovrascrive a sua volta la variabile PAGER Per default, man usa /usr/bin/less -is.

-B  Specifica quale browser usare con i file HTML. Questa opzione sovrascrive la variabile d'ambiente BROWSER Per default man usa /usr/bin/lynx,

-H  Specifica un comando che riproduce i file HTML come testo. Questa opzione sovrascrive la variabile d'ambiente HTMLPAGER Per default, man usa /usr/bin/lynx-dump,

-S  lista_sezione
    Lista è una lista di sezioni di manuale in cui cercare, separate da ":". Questa opzione sovrascrive la variabile d'ambiente MANSECT .

-a  Per default, man terminerà dopo aver visualizzato la prima pagina di manuale che trova. L'uso di questa opzione forza man a visualizzare tutte le pagine di manuale che corrispondono a nome, non solo la prima.

-c  Riformatta la pagina di manuale sorgente, anche se esiste una pagina cat aggiornata. Questo può essere importante se la pagina cat è stata formattata per uno schermo con un numero di colonne diverso, o se la pagina preformattata è danneggiata.

-d  Non visualizza le pagine di manuale, ma stampa informazioni di debug.

-D  Visualizza e stampa informazioni di debug.

-f  Equivalente di whatis.

-F or --preformat
    Formatta solo - non visualizza.

-h  stampa un messaggio di aiuto ed esce.

-k  Equivalente di apropos.

-K  Cerca la stringa specificata in *tutte* le pagine di manuale. Attenzione: questo probabilmente è molto lento! Può essere di aiuto specificare una sezione. (Solo per dare un'idea di massima, sulla mia macchina impiega circa un minuto per 500 pagine di manuale).

-m  sistema
    Specifica un insieme alternativo di pagine di manuale in cui cercare basato sul nome di sistema dato.

-p  stringa
    specifica la sequenza dei preprocessori da eseguire prima di nroff o troff. Non tutte le installazioni avranno un insieme completo di preprocessori. Alcuni dei preprocessori, e le lettere usate per designarli, sono: eqn (e), grap (g), pic (p), tbl (t), vgrind (v), refer (r). Questa opzione sovrascrive la variabile d'ambiente MANROFFSEQ .

-t  Usa /usr/bin/groff -Tps -mandoc per formattare la pagina di manuale, passando l'output a stdout. Il formato di output predefinito di /usr/bin/groff -Tps -mandoc è Postscript, fare riferimento alla pagina di manuale di /usr/bin/groff -Tps -mandoc per vedere i modi per scegliere un formato alternativo.

Secondo il formato selezionato e la disponibilità di dispositivi di stampa l'output deve passare attraverso alcuni filtri prima di essere stampato.

-w or --path
    Non visualizza le pagine di manuale, ma stampa la locazione(i) dei file che verrebbero formattati o visualizzati. Se non viene dato alcun argomento visualizza (sullo standard output) l'elenco delle directory in cui man cerca le pagine di manuale. Se manpath è un collegamento a man, allora "manpath" è equivalente a "man --path".

-W  Come -w, ma stampa i nomi di file uno per linea, senza informazioni aggiuntive. Questo è utile in comandi shell come man -aW man | xargs ls -l

PAGINE CAT
Man cercherà di salvare le pagine formattate, allo scopo di risparmiare tempo di formattazione la prossima volta che queste pagine saranno necessarie. Tradizionalmente le versioni formattate delle pagine in DIR/manX sono salvate in DIR/catX, ma possono essere specificati altri percorsi da man dir a cat dir in /etc/man.conf. Non viene salvata alcuna pagina cat quando la directory cat richiesta non esiste. Le pagine cat non vengono salvate quando sono formattate per una lunghezza della linea diversa da 80. Le pagine cat non vengono salvate quando man.conf contiene la linea NOCACHE.

E' possibile fare un suid di man a un utente man. In questo caso se una directory di cat ha come proprietario man e permessi 0755 (scrivibile solo da man), e i file cat hanno proprietario man e permessi 0644 o 0444 (scrivibili solo da man, o non scrivibili del tutto), nessun utente ordinario può cambiare le pagine cat o mettere altri file nella directory di cat. Se su man non viene fatto un suid, allora una directory cat deve avere permessi 0777 se tutti gli utenti devono poter lasciare lì le pagine cat.

L'opzione -c forza la riformattazione di una pagina, anche se esiste una pagina cat recente.

PAGINE HTML
Man troverà le pagine HTML se esse vivono in directory con nome file deve essere ".html", quindi un nome valido per una versione HTML della pagina di manuale di ls(1) sarebbe /usr/share/man/htmlman1/ls.1.html.

PERCORSO DI RICERCA DELLE PAGINE DI MANUALE
man usa un metodo sofisticato per trovare i file delle pagine di manuale, basato su opzioni di invocazione e variabili d'ambiente, il file di configurazione /etc/man.conf e alcune convenzioni e metodi euristici inclusi.

Prima di tutto, quando l'argomento nome di man contiene uno slash (/), man assume che si tratti di una specificazione di file, e non viene fatta alcuna ricerca.

Ma nel caso normale in cui nome non contenga uno slash, man cerca in una varietà di directory un file che possa essere una pagina di manuale per il nome dato.

Se si specifica l'opzione -M lista_percorsi lista_percorsi è un elenco di directory, separate da ":", nelle quali man cerca.

Se non si specifica -M ma si imposta la variabile d'ambiente MANPATH il valore di tale variabile è la lista di directory nelle quali man cerca.

Se non si specifica una lista percorsi esplicita con -M o MANPATH, man sviluppa la propria lista percorsi basata sul contenuto del file di configurazione /etc/man.conf. La dichiarazione MANPATH nel file di configurazione identifica particolari direcotry da includere nel percorso di ricerca.

Inoltre le dichiarazioni MANPATH_MAP fanno aggiunte al percorso di ricerca in funzione del proprio percorso di ricerca dei comandi (es. la propria variabile d'ambiente PATH ). Per ciascuna directory che potrebbe essere nel percorso di ricerca del comando, una dichiarazione MANPATH_MAP specifica una directory che deve essere aggiunta al percorso di ricerca dei file delle pagine di manuale. man guarda nella variabile PATH e aggiunge le directory corrispondenti al percorso di ricerca del file della pagina di manuale. Quindi, con l'uso appropriato di MANPATH_MAP, quando si dà il comando man xyz, si ottiene una pagina di manuale per il programma che verrebbe eseguito se si desse il comando xyz.

In aggiunta, per ciascuna directory nel percorso di ricerca del comando (lo chiameremo una "directory del comando") per il quale non si ha una dichiarazione MANPATH_MAP , man automaticamente cerca una directory di pagina di manuale "vicina", come una sottodirectory nella stessa directory del comando o nella directory di livello superiore della directory del comando.

Si possono disabilitare le ricerche automatiche "vicine" includendo una direttiva NOAUTOPATH in /etc/man.conf.

In ciascuna directory nel percorso di ricerca come descritto in precedenza, man cerca un file chiamato argomento.sezione, con un suffisso opzionale sul numero di sezione e magari un suffisso di compressione. Se non trova un tale file, esso allora cerca in tutte le sottodirectory che si chiamano manN o catN dove N è il numero di sezione del manuale. Se il file è in una sottodirectory catN man suppone che sia un file di una pagina di manuale formattata (pagina cat). Altrimenti man suppone che non sia formattato. In ogni caso se il nome del file ha un suffisso di compressione noto (come .gz), man suppone che sia compresso con gzip.

Se si vuole vedere dove (o se) man troverebbe la pagina di manuale per un particolare soggetto usare l'opzione --path (-w).

AMBIENTE

MANPATH
    Se MANPATH è impostata, man la usa come percorso di ricerca dei file delle pagine di manuale. Esso sovrascrive il file di configurazione e il percorso di ricerca automatico, ma è sovrascritta a sua volta dall'opzione di invocazione -M Vedere PERCORSO DI RICERCA DELLE PAGINE DI MANUALE.

MANPL
    Se MANPL è impostata il suo valore è usato come lunghezza della pagina da visualizzare. Altrimenti l'intera pagina di manuale occuperà una (lunga) pagina.

MANROFFSEQ
    Se MANROFFSEQ è impostata il suo valore è usato per determinare l'insieme di preprocessori da eseguire prima di eseguire nroff o troff. Per default le pagine vengono passate attraverso il preprocessore tbl prima di nroff.

MANSECT
    Se MANSECT è impostata il suo valore è usato per determinare in quali sezioni del manuale cercare.

MANWIDTH
    Se MANWIDTH è impostata il suo valore è usato come ampiezza a cui le pagine di manuale devono essere visualizzate. Altrimenti le pagine possono essere visualizzate sull'intera larghezza del proprio schermo.

MANPAGER
    Se MANPAGER è impostata il suo valore è usato come nome del programma da usare per visualizzare la pagina di manuale. Se non lo è allora viene usata PAGER . Se nemmeno questa è impostata, viene usato /usr/bin/less -is .

BROWSER
    Il nome di un browser da usare per visualizzare le pagine di manuale HTML. Se non è impostata viene usato /usr/bin/lynx .

HTMLPAGER
    Il comando da usare per riprodurre le pagine di manuale HTML come testo. Se non è impostata viene usato /usr/bin/lynx -dump .

LANG
    Se LANG è impostata il suo valore definisce il nome della sottodirectory ove man fa la prima ricerca delle pagine di manuale. Perciò il comando `LANG=dk man 1 foo' farà sì che man cerchi la pagina di manuale foo in .../dk/man1/foo.1, e, se non può trovare tale file, allora in .../man1/foo.1, dove ... è una directory nel percorso di ricerca.

NLSPATH, LC_MESSAGES, LANG
    Le variabili d'ambiente NLSPATH e LC_MESSAGES (o LANG quando l'ultima non esiste) giocano un ruolo nel localizzare il catalogo messaggi. (Ma i messaggi in inglese sono compilati nel programma, e per l'inglese non è necessario alcun catalogo). Notare che anche programmi come col(1) chiamati da man usano ad es. LC_CTYPE.

PATH
    PATH aiuta a determinare il percorso di ricerca dei file delle pagine di manuale. Vedere PERCORSO DI RICERCA DELLE PAGINE DI MANUALE.

SYSTEM
    SYSTEM è usata per ottenere il nome di sistema alternativo (da usare con l' opzione -m ).

BACHI
L'opzione -t funziona solo se è installato un programma tipo troff.
Se si vedono lampeggiare \255 o <AD> invece dei trattini, mettere `LESSCHARSET=latin1' nel proprio ambiente.

SUGGERIMENTI
Se si aggiunge la linea
 (global-set-key [(f1)] (lambda () (interactive) (manual-entry (current-word)))) al proprio file .emacs, allora la pressione di F1 darà la pagina di manuale della chiamata di libreria alla posizione corrente del cursore.

Per ottenere una versione testuale di una pagina di manuale, senza backspace e sottolineature, provare
  # man foo | col -b > foo.mantxt

AUTORE
John W. Eaton è l'autore originale di man. Zeyd M. Ben-Halim ha rilasciato man 1.2, e Andries Brouwer le versioni da 1.3 a 1.5p. Federico Lucifredi <flucifredi@acm.org> è il maintainer attuale.

VEDERE ANCHE
apropos(1), whatis(1), less(1), groff(1), man.conf(5).