Manpages

NOME

man - un’interfaccia ai manuali di riferimento in linea

SINTASSI

man [-c|-w|-tZ] [-H[browser]] [-Tdispositivo] [-X[dpi]] [-adhu7V] [-i|-I] [-m sistema[,...]] [-L locale] [-p stringa] [-C file] [-M percorso] [-P paginatore] [-r prompt] [-S lista] [-e estensione] [[sezione] pagina ...] ...
man -l [-7] [-tZT] [-H[browser]] [-Tdispositivo] [-X[dpi]] [-p stringa] [-P paginatore] [-r prompt] file ...
man -k [apropos opzioni] espr_reg ...
man -f [whatis opzioni] pagina ...

DESCRIZIONE

man è il paginatore dei manuali del sistema. Di solito ognuno degli argomenti pagina dati a man è il nome di un programma, di un’utility o di una funzione. La pagina di manuale associata con ognuno di questi argomenti è poi trovata e mostrata. Una sezione, se fornita, indirizzerà man a guardare solo in quella sezione del manuale. L’azione predefinita è di ricercare in tutte le sezioni disponibili seguendo un ordine prestabilito e di mostrare solo la prima pagina trovata, anche se pagina esiste in diverse sezioni.

La seguente tabella mostra i numeri delle sezioni del manuale seguiti dai tipi di pagine che contengono

Una pagina di manuale consta di diverse parti.

Queste possono essere etichettate NOME (NAME), SINTASSI (SYNOPSIS), DESCRIZIONE (DESCRIPTION), OPZIONI (OPTIONS), FILE (FILES), VEDERE ANCHE (SEE ALSO), PROBLEMI (BUGS) e AUTORE (AUTHOR).

Le seguenti convenzioni si applicano alla sezione SINTASSI e possono essere usate come una guida per le altre sezioni.

L’illustrazione del comando o funzione è un modello che dovrebbe corrispondere a tutte le possibili invocazioni. In alcuni casi è preferibile illustrare diverse invocazioni che si escludono a vicenda
come mostrato nella sezione SINTASSI di questa pagina di manuale.

ESEMPI

man ls

Mostra la pagina di manuale per la voce (programma) ls.

man -a intro

Mostra, in successione, tutte le pagine di manuale intro disponibili nel manuale. È possibile uscire tra due visualizzazioni successive o saltarne una qualsiasi.

man -t alias | lpr -Pps

Formatta la pagina di manuale indicata da ’alias’, solitamente una pagina di manuale della shell, nel formato predefinito di troff o groff e la redireziona, tramite pipe, alla stampante chiamata ps. L’output predefinito per groff è di solito in PostScript. man --help dovrebbe mostrare quale preprocessore è collegato con l’opzione -t.

man -l -Tdvi ./foo.1x.gz > ./foo.1x.dvi

Questo comando decomprime e formatta il sorgente nroff della pagina di manuale ./foo.1x.gz in un file device independent (dvi) . La redirezione è necessaria in quanto l’opzione -T fa sì che l’output sia diretto verso lo stdout senza nessun paginatore. L’output può essere visto con un programma tipo xdvi o ulteriormente convertito in PostScript usando un programma tipo dvips.

man -k printf

Cerca la parola chiave printf nelle descrizioni brevi e nei nomi delle pagine considerandola una espressione regolare. Mostra qualsiasi corrispondenza. Equivalente a apropos -r printf.

man -f smail

Cerca le pagine di manuale indicate da smail e mostra una breve descrizione di tutte quelle trovate. Equivalente a whatis -r smail.

PANORAMICA

Molte sono le opzioni disponibili per man in modo da fornire all’utente la maggior flessibilità possibile. Possono essere fatti cambiamenti al percorso di ricerca, all’ordine delle sezioni, al preprocessore per l’output, e ad altri comportamenti e operazioni elencati in dettaglio più avanti.

Se impostate, alcune variabili d’ambiente sono interrogate per determinare le funzionalità di man. È possibile impostare la variabile "omni comprensiva" $MANOPT ad una stringa qualsiasi nel formato della riga di comando, con l’eccezione che ogni spazio che sia parte integrante dell’argomento di un’opzione deve essere preceduto da un backslash (’\’). man analizzerà $MANOPT prima di analizzare la propria riga di comando. Quelle opzioni che richiedono un argomento, saranno ridefinite se le stesse opzioni si trovano anche nella riga di comando. Per annullare tutte le opzioni impostate in $MANOPT, può essere specificato -D come opzione iniziale della riga di comando. Ciò permette a man di "dimenticare" le opzioni specificate in $MANOPT sebbene debbano restare ancora valide.

Le utility per le pagine di manuale raggruppate nel pacchetto man-db fanno un uso intenso delle cache di index. Tali cache contengono informazioni come la posizione di ogni pagina di manuale nel filesystem e cosa contiene il relativo whatis (breve descrizione della pagina di manuale), inoltre permettono a man di cercare le pagine molto più velocemente rispetto ad una ricerca su file system per ogni pagine da cercare. Se richiesto tramite l’opzione -u man può verificare che tali cache rimangano consistenti, in modo da non dover lanciare manualmente del software per aggiornare le tradizionali basi di dati di whatis.

Se man non può trovare una base di dati index inizializzato da mandb per una particolare gerarchia di pagine di manuale, cercherà comunque la pagina di manuale richiesta sebbene sarà necessario un globbing dei file per effettuare la ricerca all’interno di quella gerarchia (N.d.T: con globbing [jargon] si intende l’espansione dei caratteri speciali all’interno di un nome costruito con wildcard - caratteri jolly). Invece se whatis o apropos non trovano la base di dati index, proveranno comunque a estrarre le informazioni dalla base di dati whatis tradizionale.

Queste utility supportano i file sorgente nroff compressi, che abbiano, di default, una fra le seguenti estensioni .Z, .z e .gz. È possibile trattare con qualsiasi estensione di file compresso, ma questa informazione deve essere nota al momento della compilazione. Inoltre, normalmente, qualsiasi pagina cat prodotta è compressa usando gzip. Ognuna delle gerarchie ’globali’ delle pagine di manuale, come /usr/share/man o /usr/X11R6/man, può avere una directory qualsiasi come gerarchia delle pagine cat. Tradizionalmente le pagine cat sono salvate sotto la stessa gerarchia delle pagine di manuale, ma per ragioni come quelle specificate nel Linux File System Standard (FSSTND), è meglio salvarle da qualche altra parte. Per i dettagli su come ciò sia possibile, si legga manpath(5). Per i dettagli sul perché fare ciò, si legga lo standard.

Con questo pacchetto è disponibile il ’’supporto internazionale’’: le pagine di manuale nella lingua nativa sono accessibili (se disponibili nel proprio sistema) usando le funzioni locale. Per attivare tale supporto, è necessario impostare $LC_MESSAGES e $LANG o qualche altra variabile d’ambiente dipendente dal sistema, alla propria lingua locale, solitamente specificata nel formato basato sul POSIX 1003.1:

<lingua>[_<zona>[.<set-di-caratteri>[,<versione>]]]

Se la pagina desiderata è disponibile nel proprio locale, sarà mostrata al posto della pagina standard (di solito in Inglese Americano).

Il supporto internazionale per i cataloghi di messaggi è un’altra caratteristica di questo pacchetto e può essere attivato, sempre se disponibile, nello stesso modo. Se si trova che le pagine di manuale e i cataloghi dei messaggi forniti con questo pacchetto non sono disponibili per la propria lingua e si vuole fornirli, si contatti il manutentore il quale coordinerà tali attività.

Per informazioni riguardanti altre caratteristiche ed estensioni disponibili con questo paginatore dei manuali, si leggano i documenti forniti con il pacchetto.

COMPORTAMENTO PREDEFINITO

man cercherà la pagina di manuale desiderata all’interno delle cache delle basi di dati index. Se l’opzione -u viene specificata, è eseguita una verifica della consistenza della cache per assicurarsi che le basi di dati riflettano accuratamente il filesystem. Non è generalmente necessario eseguire mandb dopo che le cache sono state create inizialmente, finché una di questa non sia in qualche modo corrotta. Il controllo della cache su sistemi con molte pagine di manuale può essere piuttosto lungo; per questo non viene svolto automaticamente, ma gli amministratori di sistema possono esseguire mandb settimanalmente per aggiornare la base di dati. Per superare eventuali problemi causati da cache non aggiornate man passa automaticamente al ’file globbing’ se una ricerca nella cache non ha esito, allo stesso modo di quando la cache non è presente.

Una volta che una pagina di manuale è stata localizzata, è eseguita una verifica per scoprire se il relativo file ’cat’ preformattato esiste già e se è più recente del file nroff. Se è così, questo file preformattato è (di solito) decompresso e poi visualizzato tramite un paginatore. Il paginatore può essere specificato in diversi modi oppure viene usato quello predefinito (si veda l’opzione -P per i dettagli). Se non c’è la pagina cat o è più vecchia del file nroff, quest’ultimo è filtrato attraverso vari programmi ed è mostrato immediatamente.

Se può essere prodotto un file cat (esiste la relativa directory cat e ha i permessi appropriati), man comprimerà e salverà il file cat in background.

Quanti e quali filtri usare viene determinato in svariati modi. Per prima cosa è interrogata l’opzione della riga di comando -p o la variabile d’ambiente $MANROFFSEQ. Se -p non è usata e la variabile d’ambiente non è impostata, viene analizzata la riga iniziale del file troff per cercare una "stringa preprocessore". Per contenere una stringa preprocessore valida, la prima riga deve assomigliare a

’\" <stringa>

dove stringa può essere una combinazione qualsiasi delle lettere descritte più avanti dall’opzione -p.

Se nessuno dei metodi suddetti fornisce informazioni sui filtri, ne è usato un insieme predefinito.

Una pipeline di formattazione è creata dai filtri al formattatore primario (nroff o [tg]roff con -t) ed eseguita. Alternativamente, se esiste un programma eseguibile mandb_nfmt (o mandb_tfmt con -t) nella radice dell’albero dei manuali, questo è eseguito. Gli viene passato il file sorgente del manuale, la stringa preprocessore, ed eventualmente il dispositivo specificato come argomento di -T o -E.

OPZIONI

Le opzioni che non richiedono argomenti, duplicate nelle riga di comando, in $MANOPT, o in entrambe sono dannose. Per le opzioni che richiedono un argomento, ogni duplicazione annullerà il valore del precendente argomento.
-l, --local-file

Attiva il modo ’locale’. Formatta e visualizza file di manuale locali invece di effettuare una ricerca nella collezione di manuali del sistema. Ogni argomento pagina sarà interpretato come un file sorgente nroff nel formato corretto. Non è creato il file cat. Se ’-’ è elencato fra gli argomenti, l’input sarà preso dallo stdin. Quando non è usata questa opzione, e man non trova la pagina richiesta, prima di mostrare un messaggio d’errore, prova a comportarsi come se fosse fornita questa opzione, usando il nome come nome di un file e cercando una corrispondenza esatta.

-L locale, --locale=locale

man di solito determinerà il proprio locale attuale chiamando la funzione C setlocale(3) che interroga diverse variabili d’ambiente, tra le quali $LC_MESSAGES e $LANG. Per ridefinire temporaneamente il valore così determinato, si usi questa opzione per fornire direttamente una stringa locale a man. Si noti che ciò non avrà effetto finché non è iniziata realmente una ricerca. L’output, come ad esempio il messaggio d’aiuto, sarà sempre visualizzato nel locale determinato inizialmente.

-D, --default

Questa opzione è solitamente data come prima opzione e reinizializza il comportamento di man a quello predefinito. È usata per reinizializzare quelle opzioni che possono essere state impostate in $MANOPT. Qualsiasi opzione successiva -D avrà il solito effetto.

-C file, --config-file=file

Usa il file di configurazione speficiato al posto di ~/.manpath.

-M percorso, --manpath=percorso

Specifica un percorso man alternativo. Normalmente man usa il codice derivato da manpath per determinare il percorso di ricerca. Questa opzione ha priorità sulla variabile d’ambiente $MANPATH e fa sì che questa e l’opzione -m siano ignorate.

Un percorso specificato come manpath deve essere la radice di una gerarchia di pagine di manuali strutturate in sezioni come descritto nel manuale di man-db (nella sezione "The manual page system"). Per vedere le pagine di manuali esterne a questa gerarchia, si usi l’opzione -l .

-P paginatore, --pager=paginatore

Specifica quale paginatore dell’output usare. Normalmente man usa pager. Questa opzione ha priorità sulla variabile d’ambiente $PAGER e non va usata assieme con -f o -k.

-r prompt, --prompt=prompt

Se una versione recente di less è usata come paginatore, man proverà ad impostare il suo prompt e alcune sue opzioni. Il prompt predefinito assomiglierà a  

Pagina di Manuale nome(sez) riga x

dove nome denota il nome della pagina di manuale, sez denota la sezione in cui è stata trovata e x è il numero di riga corrente. Ciò è ottenuto usando la variabile d’ambiente $LESS.

Fornendo l’opzione -r seguita da una stringa si può modificare il prompt predefinito. La stringa può contenere il testo $MAN_PN il quale sarà espanso nel nome della pagina di manuale corrente e il nome della sua sezione racchiuso tra ’(’ e ’)’. La stringa usata per produrre il default potrebbe essere espressa come

\ Pagina\ di\ Manuale\ \$MAN_PN\ ?ltriga\ %lt?L/%L.:
byte\ %bB?s/%s..?\ (FINE):?pB %pB\\%..

È stata spezzata in due righe solo per migliorarne la leggibilità. Per il suo significato si veda la pagina di manuale less(1). La stringa di prompt per prima cosa è valutata dalla shell. Perciò le doppie virgolette ’"’, le virgolette rovesce ’’’ e i backslash ’\’ devono essere preceduti da ’\’. La stringa di prompt potrebbe terminare con un ’\$’ il quale può essere seguito da ulteriori opzioni per less. Di default man imposta le opzioni -ix8.

Se si vuole eliminare completamente la gestione del prompt da parte di man si faccia uso della variabile d’ambiente $MANLESS descritta sotto.

-7, --ascii

Quando visualizza una pagina di manuale in ascii(7) puro su di un terminale a 7 bit o su un emulatore di terminale, alcuni caratteri potrebbero non essere visualizzati correttamente se si usa il descrittore di dispositivo latin1(7) con il GNU nroff. Questa opzione permette alle pagine di manuale in ascii puro di essere visualizzate in ascii con il dispositivo latin1. Non tradurrà alcun testo latin1. La seguente tabella mostra le traduzioni effettuate: alcune parti di essa potrebbero essere mostrate in maniera corretta solo usando il dispositivo latin1(7) di GNU nroff.

Se la colonna latin1 è visualizzata correttamente, il proprio terminale può essere configurato per i caratteri latin1 e questa opzione non è necessaria. Se le colonne latin1 e ascii sono identiche, si sta leggendo questa pagina usando questa opzione oppure man non l’ha formattata usando il descrittore di dispositivo latin1. Se manca la colonna latin1 o è corrotta, può essere necessario visualizzare le pagine di manuale usando questa opzione.

Questa opzione è ignorata quando si usano le opzioni -t, -H, -T o -Z e può essere inutile per nroff diversi dalla versione GNU.

-S lista, --sections=lista

Lista è un elenco ordinato di sezioni di manuale su cui effettuare la ricerca. Usando questa opzione viene ignorata la variabile d’ambiente $MANSECT.

-a, --all

Normalmente, man uscirà dopo aver visualizzato la pagina di manuale più adatta che trova. Usando questa opzione si forza man a visualizzare tutte le pagine di manuale con i nomi che corrispondono al criterio di ricerca.

-c, --catman

Questa opzione non è di uso generale e dovrebbe essere usata solo dal programma catman.

-d, --debug

Non mostra alcuna pagina di manuale, ma mostra un sacco di informazioni per il debug.

-e sotto-estensione, --extension=sotto-estensione

Alcuni sistemi incorporano nella gerarchia principale delle pagine di manuale grossi pacchetti di pagine di manuale, come quelle che accompagnano il pacchetto Tcl. Per ovviare ai problemi dovuti alla presenza di pagine di manuale con lo stesso nome come exit(3), le pagine di Tcl sono di solito assegnate alla sezione l. Poiché questa non è una scelta fortunata, è ora possibile mettere le pagine nella sezione corretta, ed in questo caso assegnare l’estensione specifica exit(3tcl). Durante il funzionamento normale, man visualizzerà exit(3) piuttosto che exit(3tcl). Per trattare questa situazione ed evitare la necessità di sapere in quale sezione di trova la pagina di manuale richiesta, è ora possibile dare a man una stringa di sotto-estensione che indica a quale pacchetto deve appartenere la pagina. Usando il precedente esempio, passando l’opzione -e tcl a man verrà ristretta la ricerca alle pagine che hanno estensione *tcl.

-f, --whatis

Equivalente a whatis. Mostra, se disponibile, una breve descrizione tratta della pagine di manuale. Si veda whatis(1) per i dettagli.

-h, --help

Mostra un messaggio d’aiuto ed esce.

-i, --ignore-case

Non fa distinzione tra maiuscole e minuscole durante la ricerca della pagine. Questo è il comportamento normale

-I, --match-case

Effettua la ricerca della pagina facendo distinzione tra lettere minuscole e maiuscole.

-k, --apropos

Equivalente a apropos. Cerca nelle descrizioni brevi delle pagine di manuale le occorrenze delle parole chiave e visualizza qualsiasi corrispondenza. Si veda apropos(1) per i dettagli.

-m sistema[,...], --systems=sistema[,...]

Se questo sistema ha accesso alle pagine di manuale di altri sistemi operativi, si può accedere a quest’ultime usando questa opzione. Per cercare una pagina di manuale nella collezione delle pagine di manuale di NewOS, si usi l’opzione -m NewOS.

Il sistema specificato può essere una combinazione di nomi di sistemi operativi separati da virgole. Per includere una ricerca fra le pagine di manuale del sistema operativo nativo, si includa il nome di sistema man nella stringa argomento. Usando questa opzione verrà ignorata la variabile d’ambiente $SYSTEM.

-p stringa, --preprocessor=stringa

Specifica la sequenza di preprocessori da lanciare prima di nroff o troff/groff. Non tutte le installazioni avranno l’insieme completo di preprocessori. Alcuni dei preprocessori e le lettere che li designano sono: eqn (e), grap (g), pic (p), tbl (t), vgrind (v), refer (r). Usando questa opzione viene ignorata la variabile d’ambiente $MANROFFSEQ. zsoelim è sempre lanciato come primo preprocessore.

-u, --update

Questa opzione fa in modo che man effettui un controllo a livello di ’inode’ sulla propria base di dati per assicurarsi che sia una accurata rappresentazione del file system. Il suo effetto è positivo solo se man è installato con il bit setuid impostato.

-t, --troff

Usa groff -mandoc per formattare la pagina di manuale nello stdout. Questa opzione non è richiesta assieme a -H, -T o -Z.

-T[dispositivo], --troff-device[=dispositivo]

Questa opzione è usata per cambiare l’output di groff (o se possibile quello di troff) per adattarlo ad un dispositivo diverso da quello predefinito. Implica -t. Esempi (forniti con Groff-1.17) comprendono dvi, latin1, ps, utf8, X75 e X100.

-X[dpi], --gxditview[=dpi]

Questa opzione mostra l’output di groff in una finestra grafica usando il programma gxditview. dpi (punti per pollice) può essere 75, 75-12, 100 o 100-12, con valore predefinito 75; le varianti -12 usano un font da 12 punti. Questa opzione implica -T con i dispositivi X75, X75-12, X100, X100-12 rispettivamente.

-Z, --ditroff

groff lancerà troff e poi userà un appropriato post-processore per produrre un output adatto per il dispositivo scelto. Se groff -mandoc è groff, questa opzione è passata a groff e verrà soppresso l’uso del post-processore. Implica -t.

-H[browser], --html[=browser]

Questa opzione indica a groff di produrre un output HTML, e mostra tale output in un browser web. La scelta del browser è opzionale ed è determinata dall’argomento opzionale browser se questo è fornito; altrimenti dalla variabile $BROWSER oppure dal valore definito durante la compilazione (in genere lynx). Questa opzione implica -t, e funziona solo con la versione GNU di troff.

-E dispositivo, --encoding=dispositivo

Genera un output usando una codifica di caratteri diversa dal valore predefinito. Per il modo nel quale nroff è strutturato, l’argomento di questa opzione deve essere un dispositivo di nroff come ascii, latin1 o utf8.

-w, --where, --location

Non mostra veramente le pagine di manuale, ma stampa le posizioni dei file che sarebbero stati formattati.

-W, --where-cat, --location-cat

Non mostra veramente le pagine di manuale, ma stampa le posizioni dei file cat che sarebbero stati visualizzati. Se entrambi -w e -W vengono specificati, li stampa separati da uno spazio.

-V, --version

Mostra informazioni sulla versione.

STATI D’USCITA

VARIABLI D’AMBIENTE

MANPATH

Se $MANPATH è impostata, il suo valore è usato come percorso per la ricerca delle pagine di manuale.

MANROFFSEQ

Se $MANROFFSEQ è impostata, il suo valore è usato per determinare l’insieme dei preprocessori attraverso i quali va passata la pagina di manuale. La lista dei preprocessori predefiniti dipende dal sistema.

MANSECT

Se $MANSECT è impostata, il suo valore è una lista separata da ’:’ di sezioni ed è usata per determinare in quali sezioni di manuale cercare e in quale ordine.

MANLESS

Se $MANLESS è impostata, man non effettuerà alcuna operazione per impostare una stringa di prompt per il pager less. Invece, il valore di $MANLESS verrà passato senza modifiche $LESS. Ad esempio, per impostare il prompt a “la mia stringa prompt”, impostare $MANLESS to ’-Psla mia stringa prompt’.

BROWSER

Se $BROWSER è impostata, il suo valore deve essere una lista di comandi separati da virgole, ciascuno dei quali viene provato nell’ordine per cercare di eseguire un browser web per man --html. In ogni comando %s viene sostituito da un nome di file contiene l’output HTML di groff, %% viene sostituito da un singolo carattere di percento, e %c viene sostituito dal carattere di due punti.

MANWIDTH

Se $MANWIDTH è impostata, il suo valore sarà utilizzato come lunghezza della riga per il quale le pagine di manuale verranno formattate. Se non viene impostata, le pagine saranno formattate usando una lunghezza appropriata al terminale in uso (tramite ioctl(2) se disponibile, oppure il valore di $COLUMNS, o ancora usando il valore 80 se nessuno dei due metodi precedenti funziona). Le pagine cat verranno salvate solo le la lunghezza della linea di terminale si trova tra 66 e 80 caratteri.

LANG, LC_MESSAGES

A seconda del sistema e dell’implementazione, una o entrambe le variabili $LANG e $LC_MESSAGES saranno interrogate per determinare il locale corrente. man visualizzerà i suoi messaggi usando quel locale (se disponibile). Si veda setlocale(3) per i dettagli.

FILE

/etc/manpath.config

File di configurazione di man-db.

/usr/share/man

Una gerarchia di pagine di manuale globale.

/usr/share/man/index.(bt|db|dir|pag)

Una cache della base di dati globale index tradizionale.

/var/cache/man/index.(bt|db|dir|pag)

Una cache della base di dati globale index alternativa e conforme con FSSTND.

VEDERE ANCHE

mandb(8), manpath(1), manpath(5), apropos(1), whatis(1), catman(8), less(1), nroff(1), troff(1), groff(1), zsoelim(1), setlocale(3), man(7), ascii(7), latin1(7), la pagina del pacchetto man-db, FSSTND.

CRONOLOGIA

1990, 1991 - Originalmente scritta da John W. Eaton (jwe [AT] che.edu).

23 Dicembre 1992: Rik Faith (faith [AT] cs.edu) applica le soluzioni ai problemi fornite da Willem Kasdorp (wkasdo [AT] nikhefk.nl).

30 Aprile 1994 - 23 Febbraio 2000: Wilf. (G.Wilford [AT] ee.uk) ha iniziato lo sviluppo e il mantenimento di questo pacchetto con l’aiuto di un po’ di gente.

30 Ottobre 1996 - 30 Marzo 2001: Fabrizio Polacco <fpolacco [AT] debian.org> mantiene e migliora questo pacchetto per il progetto Debian, con l’aiuto di tutta la comunità.

31 Marzo 2001 - presente: Colin Watson <cjwatson [AT] debian.org>

Traduzione di Bortolozzo Giovanni (borto [AT] pluto.it) Aggiornamento di Giuseppe Sacco <eppesuig [AT] debian.org>