Szerkesztő:casinorum/man kézikönyv

Egy man kézikönyv lapja (a man parancsról)

A man page (a manual page rövidítése, magyar gyakorlatban elterjedt a referencia kézikönyv név is) egy online súgó (help) rendszer, amelyet a "man" (manual pages - referencia kézikönyv) utasítással hívhatunk elõ. A man kézikönyv olyan, mint egy valódi kézikönyv: referencia jellegű, az egyes parancsok, függvények, fájlformátumok (legfeljebb néhány oldal terjedelmű) rövid, de pontos ismertetésével.

Történet

A UNIX Programmer's Manual először 1971. november 3-án jelent meg. Ennek a szerzői Dennis Ritchie és Ken Thompson, Doug McIlroy felkérésére. A man lapok makróit Ted Dolotta készítette (aki később a USG első menedzsere és a System III könyv főszerzője lett). A man kézikönyv minden rendszeren elérhető, és napjainkban is elterjedten használt az egyszerűsége és megbízhatósága miatt. Kevés alternatív változat létezik, ilyen például a texinfo , ami a legöregebb és legegyszerűbb hipertext rendszer, nem mellesleg a mögöttes TeX miatt nyomdai minőségben is képes nyomtatni. A Linux GUI rendszerek megjelenésével a dokumentáció HTML formátumban is elérhető.

A kézikönyv felépítése

A man referencia kézikönyv fejezetekből, alfejezetekből (vagy más néven alcsoportokból) áll. Tartalmazza továbbá az egyes parancsok lapjait, valamint a találathoz hasonló parancsok permutált indexét (egy rövid tárgymutató-szerű hivatkozást). Általában a referencia kézikönyv oldalai angol nyelven vannak írva, de a legtöbb rendszerben rendszerben más nyelven is elérhető, sőt jelentős mennyiségű magyar fordítás is készült.

Fejezetek

A referencia kötetek anyaga hagyományosan nyolc fejezetre tagolódik, ezek a következők:

Fejezet	Leírás
1	A shell-ből kiadható, a felhasználó által meghívható parancsok (segédprogramok, utility-k).
2	Rendszer hívások. A UNIX kernel számára kiadható rendszerhívások gyűjteménye, C nyelvi szintaxis szerint megadva, ahogyan egy C nyelvű programból hívhatóak.
3	Szubrutinok. A standard és opcionális rendszerkönyvtárak rutinjai, például sztringkezelés, matematikai vagy képernyővezérlő rutinok.
4	Állományformátumok.
5	Vegyes szolgáltatások, állomány és adatformátumok.
6	Számítógépes játékok és képernyőfrissítők.
7	Perifériaállományok, a fizikai perifériákat reprezentáló fájlok struktúrája, és a megfelelő eszközmeghajtó (device driver) vezérlő parancsok.
8	Rendszeradminisztráció és karbantartás. Parancsok és daemon-ok.

Alfejezetek, alcsoportok

A fenti fejezeteken belül gyakran alcsoportok is megtalálhatóak, például 3M jelöli a 3. fejezet matematikai szubrutinjait, 3N a hálózatiakat és így tovább. Az irodalomban az egyes parancsokra való hivatkozásnál zárójelek között rendszerint megadják, hogy a parancs a referencia kézikönyv melyik fejezetében található, például ls(1) azt jelenti, hogy az ls parancs a man referencia kézikönyv első fejezetében található.

Indexek

A referencia kézikönyvek elején gyakran található egy úgynevezett permutált index, amely különösen akkor tehet jó szolgálatot, ha egy konkrét feladat megoldásához van szükség programra. A permutált indexben minden egyes UNIX parancs szerepel egy egysoros leírás erejéig, de az index minden egyes parancsismertető sor minden egyes szava szerint rendezett, s így tárgymutatóként használva pillanatok alatt megtalálhatóak azok a parancsok, amelyek leírásában az általunk keresett szó szerepel.

Egy kézikönyvlap felépítése

Egy parancs leírása a kézikönyv egy lapján jelenik meg, (hasonló egy wikipédia cikkhez).

Minden man kézikönyv lapján a következő tartalmi elemek szerepelnek:

Szekció	Angolul	Leírás
Fejléc		Minimális esetben az megjelenített parancs nevét és zárójelben a kézikönyv fejezetszámát tartalmazza
NÉV (szakaszcím)	NAME	- a megjelenített téma neve és egysoros leírása
ÁTTEKINTÉS	SYNOPSYS	A téma nevét és kapcsolóit adja meg
LEÍRÁS	DESCRIPTION	A téma részletes leírása
OPCIÓK	OPTIONS	A téma (parancs) paramétereinek, kapcsolóinak részletes felsorolása és hatásainak bemutatása
VISSZATÉRÉSI ÉRTÉK	RETURN VALUES	A program vagy függvényhívás visszatérési értéke. Megállapodás szerint a void() értéket is jelölni kell. A szekció elmaradhat.
KÖRNYEZET	ENVIRONMENT	A hatásos környezeti változók felsorolása és leírása
FÁJLOK	FILES	A téma által használt (ideiglenes és konfigurációs) fájlok nevei. A szekció elmaradhat.
PÉLDÁK	EXAMPLES	A téma megértését megkönnyítő példák, ha szükség van rájuk. Elhagyható.
DIAGNOSZTIKA	DIAGNOSTICS	Tesztelési, diagnosztikai információk, amennyiben szükségesek. Elhagyható.
SZABVÁNYOK	STANARDS	Szabványok/platformok ismertetése, ha esetleges korlátozás is fennáll.
LÁSD MÉG	SEE ALSO	A témához kapcsolódó további témák felsorolása
HIBÁK	BUGS	Az ismert hibák felsorolása. Ideális esetben ez a szekció üres.
FORDÍTÁS	AUTHOR	Információk a nyelvi változatokról, pl. fordító személy, stb.
Lábléc		Opcionális információkat tartalmazhat. Nem kötelező.

Használata

Egy Unix parancsról részletesebb információkat man kézikönyvből lehet lekérdezni:

man <parancs_neve>

Például a

man ls

a lemezkatalógus használatának leírását adja meg. Magáról a man parancsról is létezik kézikönyv-oldal:

man man

A referencia kézikönyv egy fejezetére hivatkozni a man parancsban a kért lap (manual page) elé írt fejezetszámmal lehet. Például létezik a chown utasítás mellett chown rendszerhívás is. Az első fejezetben található chown utasításról a

man 1 chown

parancs, 

míg a chownrendszerhívásról a

man 2 chown

ad leírást.

A man parancs kimenete a troff tördelőprogram segítségével kulturáltan, képernyőoldalakra tördelve jelenik meg: sorkizárt 80 karakter széles, tagolt szöveg. Általában a szóköz billentyűvel lapozhatunk előre egy képernyőoldalnyit, "b"-vel (back - vissza) lapozhatunk vissza, "Enter-rel" görgethetünk csak egy sort, és "q"-val (quit)léphetünk ki. A "h"-val (help) a lapozó program parancsairól kérhetünk gyors segítséget.

Minden manual oldalnak van egy egysoros címe, ezekben keresni lehet a

man -k lisp

paranccsal: ekkor kilistázódnak azok a manual oldalcímek, amelyek tartalmazzák a keresett lisp szót - először a címhez tartozó címszót, aztán zárójelben a fejezet számát, végül az oldal rövid leírását kapjuk meg.

Átirányítások

Alapértelmezés szerint a parancs a képernyőre ír. Lehetőség van a megjelenített kimenet szövegfájlba való átirányítására. A következő példa a man parancs leírását a kimenet.txt nevű állományba irányítja át:

man man | col -b > kimenet.txt

A troff használatával PostScript kimenet is létrehozható, ez utóbbi PDF formátumba konvertálható a Ghostscript csomaggal:

 man -t foo | ps2pdf - kimenet.pdf

Példa

A man kézikönyv man oldala:

---

man(1)                                                                            man(1)

NÉV

      man - formázza és kiírja az on-line kézikönyvlapokat
      manpath - kiírja a felhasználó kézikönyvlap keresési útvonalát

ÁTTEKINTÉS

      man [-acdfhkKtwW] [-m system] [-p string] [-C config_file] [-M path] [-P pager] [-S
      fejezet_lista] [fejezet] név ...

LEÍRÁS

      A man program formázza és kiírja az on-line kézikönyvlapokat. Ez a változat  ismeri
      a  MANPATH  és  a  (MAN)PAGER  környezeti  változókat,  így személyes kézikönyvlap-
      gyűjtemények is használhatók, illetve tetszőleges program használható  a  formázott
      lapok  megjelenítésére.  Ha a parancssorban egy fejezet nevét is megadjuk, a man 
      csak azt a fejezetet vizsgálja. Parancssorból vagy környezeti változókkal megadható 
      a fejezetekben való keresés sorrendje és hogy milyen előfeldolgozót kell futtatni a
      forrásfájlokra. Ha a név '/'-jelet tartalmaz, először konkrét fájlnévként  próbálja
      kezelni,  azaz pl.  man ./foo.5 vagy man /cd/foo/bar.1.gz a megadott fájlokat fogja
      feldolgozni és megjeleníteni.

OPCIÓK

      -C  config_file
             Meghatározza  a  használandó  konfigurációs  fájl   nevét.   Alapértelmezés:
             /etc/man.config.  (Lásd man.config(5).)

      -M  path
             Meghatározza  azon  könyvtárak listáját, amelyekben a lapok keresését végzi.
             Ilyen opció hiánya esetén a MANPATH környezeti változó  tartalmát  használja
             ugyanerre   a   célra.   Amennyiben   nincs  ilyen  környezeti  változó,  az
             alapértelmezett  listát  a  /etc/man.config  -ból  veszi.  A  MANPATH   üres
             rész-sztringje az alapértelmezett listát jelenti.

      -P  pager
             Megadja, melyik lapozó (pager) programot használja. Ez az opció felülbírálja
             a  MANPAGER  környezeti  változót.  Ez  pedig  (létezése  esetén)  a   PAGER
             környezeti   változót   bírálja   felül.  Alapértelmezés  szerint  a  man  a
             /usr/bin/less-is parancsot használja lapozónak.

      -S  fejezet_lista
             A kézikönyv vizsgálandó fejezeteinek kettősponttal elválasztott listája.  Ez
             az opció felülbírálja a MANSECT környezeti változót.

      -a     Alapértelmezés  szerint  a  man program kilép az első megtalált kézikönyvlap
             kijelzése után. Ez az opció azt eredményezi, hogy a man minden  olyan  lapot
             kijelez, amely illeszkedik a név-hez. (Nemcsak az elsőt.)

      -c     Újraformázza  a  kézikönyvlap  forrását  még akkor is, ha friss előformázott
             oldal (cat page) létezik. Ennek pl. akkor lehet értelme, ha az  előformázott
             lap a jelenlegitől eltérő oszlopszámú kijelzőn lett formázva.

      -d     Nem   jeleníti   meg   a   kézikönyvlapokat,  hanem  hibakereső  (debugging)
             információkat ír ki.

      -D     Megjelenít és hibakereső információkat is ad.

      -f     Eegyenértékű a whatis paranccsal.

      -h     Egy segítő üzenetet ír ki, majd kilép.

      -k     Egyenértékű az apropos paranccsal.

      -K     A megadott sztringet minden kézikönyvlapon keresi. Figyelem: ez valószínűleg
             nagyon   lassú  lesz!   Ajánlott  legalább  a  fejezetet  megadni.

      -m  system
             Egy  másik  kézikönyvlap  készletet  ad  meg,  megadott 'system' rendszernek
             megfelelően.

      -p  sztring
             Megadja az előfeldolgozók sorozatát, amelyet az nroff vagy troff előtt  fut-
             tatni  kell. Nem minden installációnak van teljes előfeldolgozó-készlete. Az
             előfeldolgozók, és a jelölésükre szoláló betűk a következőek: eqn (e),  grep
             (g),  pic  (p),  tbl (t), vgrind (v), refer (r).  Ez az opció felülbírálja a
             MANROFFSEQ környezeti változót.

      -t     A /usr/bin/groff  -Tps  -mandoc  parancsot  használja  a  formázásra,  és  a
             kimenetet   a  standard  kimenetre  küldi.  A  /usr/bin/groff  -Tps  -mandoc
             kimenetét esetenként célszeru lehet  néhány  szuron  keresztül  átküldeni  a
             nyomtatás elott.

      -w or --path
             Nem  jeleníti  meg  a  kézikönyvlapokat,  csak  a  formázandó illetve megje-
             lenítendo fájlok neveit írja ki.  Argumentum  nélkül  a  standard  kimeneten
             listázza  a keresésre használt könyvtárakat.  Amennyiben a manpath egy kötés
             (link) a man -ra, akkor 'manpath' egyenértéku a 'man --path' paranccsal.

      -W     Ugyanaz, mint -W, csak egy fájlnevet ír soronként egyéb információk  nélkül.
             Ez olyan burokparancsoknál hasznos, mint pl.  man -aW man | xargs ls -l

ELOFORMÁZOTT OLDALAK

      A man program megpróbálja elmenteni a formázott kézikönyvlapokat, hogy megtakarítsa
      a  formázási  időt,  amikor  ugyanerre  a  lapra  lesz  a   későbbiekben   szükség.
      Hagyományosan  a  'DIR/manX'  formázott  lapjait  a  'DIR/catX'-be  menti,  de  más
      megfeleltetések is beállíthatók a /etc/man.config fájlban. Nem történik mentés,  ha
      a megfelelo 'cat' könyvtár nem létezik.

      Lehetséges  a  man  suid  bitjét beállítani a 'man' felhasználónak. Ekkor ha a cat-
      könyvtárnak 'man' a tulajdonosa, és a módja 0755 (csak a 'man' által írható), és az
      előformázott  cat-fájlok  tulajdonosa is 'man', és módjuk 0644 vagy 0444, akkor egy
      rendes felhasználó sem tudja az eloformázott lapokat lecserélni, vagy más  fájlokat
      írni a cat-könyvtárba.

      Amennyiben  a man nem suid-os, a cat-könyvtárnak 0777 módúnak kell lenni, hogy min-
      den felhasználó tudjon előfordított lapokat tenni ide.

      A -c opció  hatására  a  lap  akkor  is  újraformzádik,  ha  már  létezik  aktuális
      előformázott lap.

KÖRNYEZET

      MANPATH
             Amennyiben  a  MANPATH  nem üres, értéke a kézikönyvlapok keresési útvonalát
             adja meg.

      MANROFFSEQ
             A MANROFFSEQ tartalma az előfeldolgozók halmazát határozza meg, melyeket  az
             nroff  vagy troff elott kell futtatni. Alapértelmezés szerint a lapok a 'ta-
             ble' előfeldolgozón mennek át az nroff előtt.

      MANSECT
             A MANSECT értéke a keresendő kézikönyv fejezeteket adja meg.

      MANWIDTH
             A MANWIDTH értéke a lapok kijelzéskor használandó szélességét adja  meg.  Ha
             ez a változó üres, a lapokat a képernyő teljes szélességében jeleníti meg.

      MANPAGER
             A  MANPAGER  értéke  a formázott lap megjelenítésére szolgáló programot adja
             meg. Amennyiben üres,  a  PAGER  -t  használja.  Ha  ez  is  üres,  akkor  a
             /usr/bin/less -is parancs jeleníti meg a lapot.

      LANG   Amennyiben  a  LANG  környezeti  változó nem üres, egy könyvtárnevet ad meg,
             ahol a man először keresi a kézikönyvlapokat. Így a 'LANG=dk ;  man  1  foo'
             hatására  először  a 'DIR/dk/man1/foo.1' fájlt próbálja megjeleníteni, ha ez
             nem létezik, akkor a 'DIR/man1/foo.1'-et. Itt 'DIR' egy könyvtár a  keresési
             útvonalból.

      NLSPATH, LC_MESSAGES, LANG
             Az  NLSPATH  és  LC_MESSAGES  vagy  LANG  környezeti  változók  az  üzenetek
             katalógusának elhelyezkedésében játszanak szerepet.  (Az  angol  üzenetek  a
             programba  vannak fordítva, így ehhez a nyelvhez nem kell katalógus.) Meg-
             jegyzendő, hogy olyan programok, mint pl. a col(1), melyet a 'man' hív, szin-
             tén használják pl. az 'LC_TYPE' változót.

      PATH   A   PATH   értéke   az   alapértelmezett   kézikönyvlap   keresési   útvonal
             összeállításában játszik szerepet.

      SYSTEM A SYSTEM változót arra használja, hogy az alapértelmezett választható  rend-
             szernév értékét határozza meg. (Lásd a -m opciót.)

LÁSD MÉG

      apropos(1), whatis(1), less(1), groff(1).

HIBÁK

      A -t opció csak akkor muködik, ha egy troff-szerű program is rendelkezésre áll.
      Amennyiben villogó \255 vagy <AD> látható a '-' jel helyett, a 'LESSCHARSET=latin1'
      beállítást kell alkalmazni.

Felhasznált irodalom

• Szemethy Tivadar: Unix ismertető
• Bartók Nagy János - Laufer Judit: UNIX FELHASZNÁLÓI ISMERETEK, Openinfo Kiadó, Bp.
• Bagoly Zsolt - Papp Gábor: UNIX alapismeretek, Bp., CoDe Kft.,1995, ISBN: 9630449552

További információk

• Writing man-pages
• Writing manual pages
• Magyar Linux Dokumentációs Projekt - Kézikönyv oldalak

[[Kategória:Unix-parancsok]]