1.2 Manpages

In diesem Lab lernen wir die Verwendung von manpages kennen und schreiben zum besseren Verständnis eine eigene manpage für ein eigenes Programm.

Inhalt

• Was sind Manpages
• Wie ist eine Manpage aufgebaut?
• Verwendung von Manpages
• Erstellen einer eigenen Manpage

Was sind Manpages?

Manpages (nach dem Unix-Kommando man, was für englisch manual „Handbuch“ steht) sind eine Sammlung von Hilfe- und Dokumentationsseiten unter Unix und verwandten Betriebssystemen. Sie werden mit den Kommandos man und whatis durchsucht sowie ausgegeben. Zur schnellen Durchmusterung wird ein eigener Index, die sogenannte Whatis-Datenbank, angelegt. Manpages werden unter Zuhilfenahme des speziell konzipierten Macro-Pakets troff erzeugt.

Wann immer wir Hilfe oder Dokumentation zu einem beliebigen Programm benötigen können wir also auf die Manpage zugreifen, insofern diese auch existiert. Bei allen Standardprogrammen ist dies der Fall.

Wie ist eine Manpage aufgebaut?

Alle Manpages folgen dem selben Layout. Gegliedert wird in sogenannte Sections.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

NAME
    The name of the command or function, followed by a one-line description of what it does.
SYNOPSIS
    In the case of a command, you get a formal description of how to run it and what command line options it takes.
DESCRIPTION
    A textual description of the functioning of the command or function.
EXAMPLES
    Some examples of common usage.
SEE ALSO
    A list of related commands or functions.
BUGS
    List known bugs.
AUTHOR
   Specify your contact information.
COPYRIGHT
    Specify your copyright information.

Layout einer Manpage mit Beschreibung

Oft werden Manpages um einzelne Punkte erweitert. Dazu gehören beispielsweise EXIT STATUS, ENVIRONMENT, FILES, HISTORY, etc. Doch in der Manpage steht viel mehr als nur Programmdokumentation. Manpages enthalten auch Informationen zu Programmcode, Applikationsschnittstellen, Kernelroutinen und vieles mehr. Folgende Tabelle ist ein Auszug aus man man (Selbstverständlich existiert für das Programm man auch eine Manpage).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

    The table below shows the section numbers of the manual followed by the types of  pages  they
    contain.

    1   Executable programs or shell commands
    2   System calls (functions provided by the kernel)
    3   Library calls (functions within program libraries)
    4   Special files (usually found in /dev)
    5   File formats and conventions, e.g. /etc/passwd
    6   Games
    7   Miscellaneous (including macro packages and conventions), e.g. man(7), groff(7)
    8   System administration commands (usually only for root)
    9   Kernel routines [Non standard]

    A manual page consists of several sections.

    Conventional  section  names  include  NAME,  SYNOPSIS,  CONFIGURATION, DESCRIPTION, OPTIONS,
    EXIT STATUS, RETURN VALUE, ERRORS, ENVIRONMENT, FILES, VERSIONS, CONFORMING TO, NOTES,  BUGS,
    EXAMPLE, AUTHORS, and SEE ALSO.

Auszug aus der Manpage zu man

Verwendung von Manpages

Informationen über ein Programm abfragen

Möchte man wissen was ein Programm für Inputs erfordert oder generelle Informationen über die Argumente abfragen tut man dies folgendermassen.

1

$ man ls

Aufruf der Manpage von ls

Obige Eingabe ruft die Manpage von ls auf. Eigentlich ruft man das Programm less mit den gewünschten Argumenten auf. Daher bedient man Manpages genau gleich wie man less verwendet.

• Gescrolled wird mit j,k
• Gesucht wird mit /
• Verlassen wird eine Manpage über q
• Hilfe zu Hotkeys gibt’s mit h

Nach Manpanges suchen

Hat man keine Ahnung wo sich die gewünschte Information befinden könnte, kann man man mit Suchparameter aufrufen.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

$ man -k echo
echo (1)             - display a line of text
echo (1p)            - write arguments to standard output
echo (3x)            - curses input options
echo_sp (3x)         - curses screen-pointer extension
echo_wchar (3x)      - add a complex character and rendition to a curses window, then advance the cu...
echochar (3x)        - add a character (with attributes) to a curses window, then advance the cursor
gifecho (1)          - generate a GIF from ASCII text
lessecho (1)         - expand metacharacters
noecho (3x)          - curses input options
noecho_sp (3x)       - curses screen-pointer extension
pam_echo (8)         - PAM module for printing text messages
pecho_wchar (3x)     - create and display curses pads
pechochar (3x)       - create and display curses pads
ping (8)             - send ICMP ECHO_REQUEST to network hosts
wecho_wchar (3x)     - add a complex character and rendition to a curses window, then advance the cu...
wechochar (3x)       - add a character (with attributes) to a curses window, then advance the cursor
xmessage (1)         - display a message or query in a window (X-based /bin/echo)

Suche nach allen Einträgen für echo

Wie wir sehen liefert eine Suche nach echo einige Resultate. In den Klammern wird jeweils die Section angegeben. Suchen wir also nach der Dokumentation für Shellprogramme sollte man sich auf die 1-er Sections konzentrieren. Wollen wir uns eine Spezifische manpage ansehen gilt folgende Syntax.

1
2
3

man 1 echo  # hier landen wir in der Nutzerdokumentation
man 1p echo # hier landen wir in der Doku für Programmierer
man 3 echo  # hier landen wir in der C-Library Dokumentation für das echo ncurses interface

Applikationsdokumentation von echo

Wir sehen also dass wir über die Manpages nicht nur erfahren wie ein Programm funktioniert, sondern auch wie wir den Programmcode nutzen und gegebenenfalls anpassen können. Dies funktioniert selbstverständlich nicht nur mit echo sondern mit beliebigen Suchbegriffen. Ein gutes Beispiel ist die Dokumentation der ASCII Table welche man mittels man ascii aufruft. Sie ist sehr hilfreich um nachzuschlagen welcher ASCII-Wert zu welchem Zeichen korrelliert.

Erstellen einer eigenen Manpage

Wo leben Manpages im Dateisystem?

Manpages der Standardwerkzeuge werden unter /usr/share/man/man1 installiert und mittels gzip komprimiert, damit sie möglichst wenig Platz benötigen.

1
2
3

$ cd /usr/share/man/man1
$ ls -l         # Output gekürzt
$ zcat ls.1.gz  # Output gekürzt

Beispiel Rohausgabe einer Manpage für ls

Die Orte unter welcher Manpages automatisch mittels man indexiert werden und somit gesucht werden können sind in der Variable MANPATH abgelegt. Sie erinnert ein wenig an die globale PATH Variable. Erstellt man eigene Manpages sollte man sich daran halten. Defaultwerte stehen in der Konfigurationsdatei /etc/man.config. Diese Werte können natürlich auch angepasst werden. Mehr dazu liefert die entsprechende Manpage man manpath. ;-)

Wie baue ich denn nun eine Eigene Manpage?

Stellen wir uns vor dass wir ein Programm geschrieben hätten welches bei Puzzle Pizza bestellt. Wir nennen es ppizza. Beim Aufruf von ppizza wird bei darina.ch eine Zufallspizza bestellt welche dann abhängig vom momentan arbeitenden Personal nach einigen Minuten abgeholt werden kann. Mittels ppizza -v kann eine zufällige, vegetarische Pizza bestellt werden.

Schreiben wir nun also eine Manpage für dieses Programm. Dazu müssen wir uns an die eigenartige Syntax des Programmes GNU Troff groff halten.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

.\" Manpage for ppizza.
.\" Contact systems@puzzle.ch to correct errors or typos.
.TH man 8 "26 April 2020" "1.0" "ppizza man page"
.SH NAME
ppizza \- order delicious random pizzas from darina.ch
.SH SYNOPSIS
ppiza [OPTION]
.SH DESCRIPTION
ppiza is a utility which lets you order random pizzas.
.SH OPTIONS
-v, --vegetarian \- order random vegetarian pizza
.SH BUGS
Some argue, not always ordering a PREFERITA is a bug, we consider this a feature
.SH AUTHOR
systems@puzzle.ch

Erstellen einer eigenen Manpage

Speichert man den obigen Text in einem Dokument names ppizza kann man es mit man ./ppizza öffnen und wird mit einer wunderschönen neuen Manpage begrüsst. Der Author streitet an dieser Stelle ab dass so ein Programm existiert.

Wie installiere ich denn nun meine eigene Manpage?

Ganz einfach, man komprimiert sie mit gzip und kopiert sie in einen Ordnder welcher unter manpath aufgelistet ist.

1
2
3

# cp ppizza /usr/local/man/man8/ppizza.8
# gzip /usr/local/man/man8/ppizza.8
$ man ppizza

Installation der eigenen Manpage