man(n) Utility per le Pagine di Manuale man(n) NOME man - un'interfaccia ai manuali di riferimento in linea SINTASSI man [-c|-w|-tZT dispositivo] [-adhu7V] [-m sistema[,...]] [-L locale] [-p stringa] [-M percorso] [-P paginatore] [-r prompt] [-S lista] [-e estensione] [[sezione] pag- ina ...] ... man -l [-7] [-tZT dispositivo] [-p stringa] [-P pagina- tore] [-r prompt] file ... [apropos opzioni] espr_reg ... [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 predefinito e di mostrare solo la prima pagina trovata, anche se pagina esiste in diverse sezioni. La seguente tabella mostra i numeri delle sezioni del man- uale seguiti dai tipi di pagine che contengono tab (@); l l. 1@Programmi eseguibili e comandi della shell 2@Chiamate al sistema (funzioni fornite dal kernel) 3@Chiamate alle librerie (funzioni all'interno delle @librerie di sistema) 4@File speciali (di solito trovabili in /dev) 5@Formati dei file e convenzioni p.es. /etc/passwd 6@Giochi 7@Pacchetti di macro e convenzioni p.es. man(n), groff(f). 8@Comandi per l'amministrazione del sistema (solitamente @solo per root) 9@Routine del kernel [Non standard] 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. tab (@); l l. testo in grossetto@scrivere esattamente come mostrato. testo in corsivo@rimpiazzare con un argo- mento appropriato. [-abc]@ognuno o tutti gli argomenti all'interno @di [ ] sono opzionali. -a|-b@opzioni sepa- rate da | non possono essere @usate assieme. argomento ...@argomento ripetibile. [espressione] ...@l'intera espressione all'interno @di [ ] ripetibile. L'illustrazione del comando o funzione un modello che dovrebbe corrispondere a tutte le possibili invocazioni. In alcuni casi preferibile illustrare diverse invocazioni esclusive 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 contenute 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 colle- gato 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 ulterior- mente 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. Equiva- lente a apropos -r printf. man -f smail Cerca le pagine di manuale indicate da smail e mostra una breve descrizione di tutte quelle trovate. Equiv- alente a whatis -r smail. PANORAMICA Molte sono le opzioni disponibili a 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, le varie variabili d'ambiente sono interro- gate per determinare le operazioni 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 analiz- zare 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 inizializzare 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 pac- chetto man_db fanno un uso intenso delle cache delle basi di dati index. Tali cache contengono informazioni come la posizione di ogni pagina di manuale nel filesystem e cosa contiene il relativo whatis (breve descrizione della pag- ina di manuale). Uno dei compiti di man assicurare che tali cache rimangano consistenti. Queste cache delle basi di dati evitano il bisogno di dover lanciare manualmente del software per aggiornare le tradizionali basi di dati whatis in formato testo, ed inoltre permettono a man di girare pi veloce di quello che farebbe se dovesse ogni volta cercare la pagina di manuale appropriata. Se man non pu trovare una base di dati index inizializzata da mandb per una particolare gerarchia di pagine di man- uale, 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 esten- sione di file compresso, ma questa informazione deve essere nota al momento della compilazione. Inoltre, di default, 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(h). Per i dettagli sul perch fare ci, si legga lo standard. Con questo pacchetto disponibile il ``supporto inter- nazionale'': 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, al proprio linguaggio locale, solitamente specificato nel formato basato sul POSIX 1003.1: <linguaggio>[_<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 manu- tentore 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 tale ricerca non ha successo, 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. 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 settata, viene analizzata la riga iniziale del file troff per cercare una "stringa preprocessore". Per contenere una stringa prepro- cessore 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 for- mattatore 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, questi eseguito. A questi passato il file sorgente del manuale, la stringa preprocessore, ed even- tualmente il dispositivo specificato come argomento di -T. OPZIONI Nessun argomento delle opzioni che non sia duplicato nelle riga di comando, in $MANOPT, o in entrambe dannoso. 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 argo- mento 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 compor- tarsi come se fosse fornita questa opzione, usando il nome come nome di un file e cercando una cor- rispondenza esatta. -L locale, --locale=locale man di solito determiner il proprio locale attuale chiamando la funzione C setlocale(e) che interroga diverse variabili d'ambiente, tra le quali $LC_MES- SAGES 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. -M percorso, --manpath=percorso Specifica un percorso man alternativo. Di default, man usa il codice derivato da manpath per deter- minare il percorso di ricerca. Questa opzione ha priorit sulla variabile d'ambiente $MANPATH e fa s che questa e l'opzione -m siano ignorate. -P paginatore, --pager=paginatore Specifica quale paginatore dell'output usare. Di default, man usa exec /usr/bin/pager -s. 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 pagina- tore, man prover ad impostare il suo prompt e alcune sue opzioni. Il prompt predefinito assomiglier a Pagina di Manuale nome(e) 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\ Man- uale\ \$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(s). La stringa di prompt per prima cosa valutata dalla shell. Perci le doppie virgolette `"', le virgolette rovesce ``' e i backslash `\' devono essere precedute da `\'. La stringa di prompt potrebbe terminare con un `\$' il quale pu essere seguito da ulteriori opzioni per less. Di default man setta le opzioni -ix8. -7, --ascii Quando visualizza una pagina di manuale in ascii(i) 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(1) con il GNU nroff. Questa opzione permette alle pagine di man- uale in ascii puro di essere visualizzate in ascii con il dispositivo latin1. Non tradurr alcun testo latin1. La seguente tabella mostra le traduzioni effettuate. tab (@); l c c c. Descrizione@Ottale@latin1@ascii _ trattino di continuazione@255@@- bullet (middle dot)@267@o@o accento acuto@264@'@' segno di molti- plicazione@327@x@x 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, -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 separate da `:' su cui effettuare la ricerca. Usando questa opzione viene ignorata la variabile d'ambiente $MANSECT. -a, --all Di default, 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 princi- pale 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(t), 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(t). Durante il fun- zionamento normale, man visualizzer exit(t) piut- tosto che exit(t). Per trattare questa situ- azione ed evitare la necessit di sapere in quale sezione di trova la pagina di manuale richiesta, ora possibile dare a man una stringa di 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(s) per i dettagli. -h, --help Mostra un messaggio d'aiuto ed esce. -k, --apropos Equivalente a apropos. Cerca nelle descrizioni brevi delle pagine di manuale le occorrenze delle parole chiave e visualizza qualsiasi corrispon- denza. Si veda apropos(s) 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 $SYS- TEM. -p stringa, --preprocessor=stringa Specifica la sequenza di preprocessori da lanciare prima di nroff o troff/groff. Non tutte le instal- lazioni avranno l'insieme completo di preproces- sori. 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 Le cache delle basi di dati index sono aggiornate `al volo', cio non necessario che mandb sia lanci- ato periodicamente per mantenerle consistenti. Se la pagina di manuale richiesta non trovata all'interno della cache o usata l'opzione -a, man far una verifica della consistenza a livello direc- tory per assicurarsi che le proprie cache siano una rappresentazione accurata del filesystem. Per forzare una verifica della consistenza a livello inode prima di trovare alcuna pagina di manuale, si usi l'opzione -u. -t, --troff Usa /usr/bin/groff -mandoc per formattare le pagine di manuale nello stdout. Questa opzione non richi- esta assieme a -T o -Z. -T dispositivo, --troff-device [=dispositivo] Questa opzione usata per cambiare l'output di groff (o se possibile quello di troff) per adat- tarlo ad un dispositivo diverso da quello pre- definito. Implica -t. Esempi (forniti con Groff-1.09) comprendono dvi, latin1, X75 e X100. -Z, --ditroff groff lancer troff e poi user un appropriato post- processore per produrre un output adatto per il dispositivo scelto. Se /usr/bin/groff -mandoc groff, questa opzione passata a groff e verr sop- presso l'uso del post-processore. Implica -t. -w, --where, --location Non mostra veramente le pagine di manuale, ma stampa le posizioni dei file che sarebbero stati formattati o visualizzati. Se il file un file cat, mostra anche la posizione del suo file sorgente nroff. -V, --version Mostra informazioni sulla versione e l'autore. STATI D'USCITA 0 L'esecuzione del programma ha avuto successo. 1 Errore d'uso, di sintassi o nel file di configu- razione. 2 Errore operativo. 3 Un processo figlio ha restituito uno stato d'uscita diverso da zero. 16 Almeno una delle pagine/file/parole chiave non esisteva e non aveva corrispondenza. 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. PAGER Se $PAGER impostata, il suo valore usato come il nome del programma da usare per visualizzare la pagina di manuale. Di default, usato exec /usr/bin/pager -s. SYSTEM Se $SYSTEM impostata, avr lo stesso effetto dell'opzione -m stringa dove stringa sar preso come il contenuto di $SYSTEM. MANOPT Se $MANOPT impostata, sar analizzata prima della riga di comando di man ed supposta essere in for- mato simile. Poich tutte le altre variabili d'ambi- ente specifiche di man possono essere specificate come opzioni della riga di comando, e sono quindi candidate per essere incluse in $MANOPT ci si pu aspettare che diventeranno obsolete. N.B.: Tutti gli spazi che dovrebbero essere interpretati come parte dell'argomento di un opzione devono essere preceduti da `\'. 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(e) per i det- tagli. 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 alterna- tiva e conforme con FHS. VEDERE ANCHE mandb(b), manpath(h), manpath(h), apropos(s), whatis(s), catman(n), less(s), nroff(f), troff(f), groff(f), zsoe- lim(m), setlocale(e), man(n), ascii(i), latin1(1), FSSTND. STORIA 1990, 1991 - Originalmente scritta da John W. Eaton (jwe@che.utexas.edu). 23 Dicembre 1992: Rik Faith (faith@cs.unc.edu) applica le soluzioni ai problemi fornite da Willem Kasdorp (wkasdo@nikhefk.nikef.nl). 30 Aprile 1994 - 23 Febbraio 2000: Wilf. (G.Wil- ford@ee.surrey.ac.uk) ha iniziato lo sviluppo e il manten- imento di questo pacchetto con l'aiuto di un po' di gente. 30 Ottobre 1996 - 30 Marzo 2001: Fabrizio Polacco <fpo- lacco@debian.org> mantiene e migliora questo pacchetto per il progetto Debian, con l'aiuto di tutta la comunit. 31 Marzo 2001 - 07 September 2001: Colin Watson <cjwat- son@debian.org> Traduzione di Bortolozzo Giovanni (borto@pluto.linux.it) 2.3.20 07 September 2001 man(n)