Moritz Lenz

Wie liest man Manpages?

Wenn man als Anfänger Linux oder Unix benutzt, so wird einem häufig gesagt, man solle sich die manpage, also die elektronische Handbuch-Seite zu einem bestimmten Programm durchlesen.

Das ist aber leichter gesagt als getan: vieles bleibt einem am Anfang unverständlich. Daher gibt es hier ein paar Tipps zum Lesen einer Manpage.

Ein erster Blick auf die Manpage

Ein Typisches Beispiel einer Manpage ist die von man selbst:

man(1)                        Manual pager utils                        man(1)

NAME
       man - an interface to the on-line reference manuals

SYNOPSIS
       man  [-c|-w|-tZ]  [-H[browser]] [-T[device]] [-adhu7V] [-i|-I] [-m sys-
       tem[,...]] [-L locale] [-p string] [-C file] [-M path] [-P  pager]  [-r
       prompt] [-S list] [-e extension] [[section] page ...] ...
       man -l [-7] [-tZ] [-H[browser]] [-T[device]] [-p string] [-P pager] [-r
       prompt] file ...
       man -k [apropos options] regexp ...
       man -f [whatis options] page ...

DESCRIPTION
       man is the system's manual pager. Each page argument given  to  man  is
       normally  the  name of a program, utility or function.  The manual page
       associated with each of these arguments is then found and displayed.  A

... und so weiter.

In der ersten Zeile steht links und rechts der name der aktuellen Manpage, dahinter in Klammern die section, also der Abschnitt, in der diese Manpage steht.

Die Bedeutung der sections im einzelnen:

section	Bedeutung
1	Ausführbare Programme und Shell-Befehle
2	Systemaufrufe
3	Bibliotheksaufrufe
4	Spezielle Dateien (z.B. Devices unter /dev)
5	Dateiformate und Konventionen
6	Spiele
7	Verschiedenes
8	Befehle zur Systemverwaltung

Zusätzlich gibt es manchmal noch section 9, in der Kernelfunktionen dokumentiert sind.

In der dritten Zeile steht NAME, dahinter nocheinmal der Names der manpage (oder mehrere, wenn in einer manpage mehrere Programme/Funktionen dokumentiert sind) sowie eine sehr kurze Beschreibung, was das dokumntierte Programm macht.

Synopsis

Dann kommt ein sehr interessanter Teil, die SYNOPSIS, auf deutsch Zusammenfassung.

Darin ist oft in kompakter Form festgehalten, wie man das Programm aufrufen kann.

Hier nochmal das Beispiel aus man man:

       man  [-c|-w|-tZ]  [-H[browser]] [-T[device]] [-adhu7V] [-i|-I] [-m sys-
       tem[,...]] [-L locale] [-p string] [-C file] [-M path] [-P  pager]  [-r
       prompt] [-S list] [-e extension] [[section] page ...] ...
       man -l [-7] [-tZ] [-H[browser]] [-T[device]] [-p string] [-P pager] [-r
       prompt] file ...
       man -k [apropos options] regexp ...
       man -f [whatis options] page ...

Jede Zeile steht für eine andere Möglichkeit, das Programm man aufzurufen.

Dabei stehen viele Möglichkeiten in eckigen Klammern [...]. Das bedeutet, dass diese Angabe optional ist, d.h. nicht erzwungen ist.

Die erste Zeile enthält nur optionale Parameter, d.h. man kann man ohne Optionen aufrufen (was aber nicht sehr interessant ist.)

Teilweise sind die eckigen Klammern ineinander verschachtelt, z.B. in [[section] page ...]. Das ist so zu verstehen, dass man, wenn man page mit angibt, kann man auch section mit angeben. Die drei Punkte ... bedeuten, dass man das beliebig oft angeben darf, also z.B.

man 1 passwd 5 passwd

Der senkrechte Strich zwischen mehrere Optionen bedeutet, dass man eine (aber auch nur eine) dieser Optionen auswählen kann, z.B. [-c|-w|-tZ] bedeutet, man darf die Optionen diese drei Optionen angeben, muss aber nicht (wegen der eckigen Klammern), und man darf nur eine auf einmal mit angeben.

Hät man sich nicht daran, so beschwert sich das Programm:

man -c -w foo
man: -c -w : incompatible options
...

Erklärungsbedürftig ist noch die Konstruktion [-adhu7V]:

Viele Programme unter Linux und Unix akzeptieren die sogenanten kurzen Optionen, die aus einem Minuszeichen - und einem einzelnen Buchstaben bestehen.

Dabe sind mehrere Buchstaben hinter einem Minuszeichen kombinierbar, also z.B. -ad anstatt -a -d.

Die Angabe [-adhu7V] bedeutet jetzt, dass man aus den angebenen Optionen beliebige Kombinationen bilden kann, also z.B. -a -7 -h oder -a7 -h oder -adh.

Tipp

In vielen Manpages wirkt die SYNOPSYS-Zeile sehr unübersichtlich. Oft braucht man aber die meisten Optionen gar nicht.

Deswegen sollte man an das Ende der Zeile schauen, da dort meistens die Angaben stehen, die man nicht weglassen darft.

DESCRIPTION

Im Abschnitt DESCRIPTION wird im Detail erklärt, was das Programm/die Funktion macht.

Meistens gibt es eine Liste der Optionen inklusive Beschreibung, was sie bewirken.

Manchmal ist die Liste der Optionen auch in einem eigenen Abschnitt OPTIONS.

Oft lohnt es sich, den ersten Absatz dieses Abschnitts durchzulesen, und dann den Rest nach gezielt Stichwörtern zu durchsuchen. Manche Manpages sind so umfangreich, dass man anders nicht weiter kommt. Zum Beispiel besteht die manpage zu gcc-3.3.5 aus 143 Druckseiten, man braucht Ewigkeiten um das alles durchzulesen.

SEE ALSO

Gerade wenn man nicht genau weiß, welche Manpage man lesen muß, um ein bestimmtes Problem zu lösen, hilft der Abschnitt SEE ALSO.

Dort gibt es Referenzen zu anderen Manpages, texinfo-Seite oder Webseiten, die mit verwandten Themen zu tun haben. Refrenzen auf andere Manpages erkennt man daran, dass hinter dem Namen der manpage in Klammern noch eine einzelne Ziffer, die section, angegeben ist.