Gliederung der Handbuchseiten¶

1 User commands (Programs)

Diese Befehle kann ein Benutzer in der Shell ausführen.

2 System calls

Diese Funktionen umhüllen (»wrap«) die vom Kernel ausgeführten Aktionen.

3 Library calls

Alle Bibliotheksfunktionen außer den Systemaufruf-Wrappern (die meisten der libc-Funktionen).

4 Special files (devices)

Dateien, die in /dev liegen und den Zugriff auf Geräte über den Kernel erlauben.

5 File formats and configuration files

Beschreibt verschiedene menschenlesbare Dateiformate und Konfigurationsdateien.

6 Games

Auf dem System verfügbare Spiele und lustige kleine Programme.

7 Overview, conventions, and miscellaneous

Überblicke oder Beschreibungen verschiedener Themen, Konventionen und Protokolle, Zeichensatz-Standards, dem Standard-Dateisystemlayout und diversen anderen Dingen.

8 System management commands

Dazu gehören Befehle wie mount(8). Viele davon können nur mit Administratorrechten ausgeführt werden.

Makropaket¶

Konventionen für die Gestaltung der Quelltexte¶

Titelzeile¶

wobei:

Abschnitte innerhalb einer Handbuchseite¶

NAME
SYNOPSIS
CONFIGURATION       [im Allgemeinen nur in Abschnitt 4]
DESCRIPTION
OPTIONS             [im Allgemeinen nur in den Abschnitten 1, 8]
EXIT STATUS         [im Allgemeinen nur in den Abschnitten 1 und 8]
RETURN VALUE        [im Allgemeinen nur in den Abschnitten 2 und 3]
ERRORS              [typischerweise nur in den Abschnitten 2 und 3]
ENVIRONMENT
FILES
ATTRIBUTES          [im Allgemeinen nur in den Abschnitten 2 und 3]
VERSIONS            [im Allgemeinen nur in den Abschnitten 2 und 3]
CONFORMING TO
NOTES
BUGS
EXAMPLE
SEE ALSO

Bitte verwenden Sie eine traditionelle Überschrift, wo sie zutreffen würde; diese Art von Konsistenz kann die Informationen leichter verständlich machen. Wenn Sie müssen, können Sie eigene Überschriften wählen, wenn die Dinge dadurch leichter zu verstehen sind. (Das kann besonders für Seiten in den Abschnitten 4 und 5 nützlich sein.) Doch bevor Sie das tun, prüfen Sie bitte, ob Sie auch traditionelle Überschriften verwenden können (und innerhalb dieser Abschnitte einige Unterabschnitte (.SS) einfügen).

Die folgende Liste geht näher auf den Inhalt jedes der oben genannten Abschnitte ein.

NAME

Der Name dieser Handbuchseiten

Lesen Sie man(7) für wichtige Hinweise zu der/den Zeile(n), die dem Befehl .SH NAME folgen sollten. Alle Wörter in dieser Zeile (darunter auch das Wort, das unmittelbar auf das »\-« folgt) sollten kleingeschrieben werden, außer wenn das Englische oder die Gepflogenheiten der Fachbegriffe es anders vorschreiben.

SYNOPSIS

Eine kurze Zusammenfassung des Befehls oder der Funktionsschnittstelle

Für Befehle beschreibt dieser Abschnitt die Syntax des Befehls und seine Argumente (einschließlich Optionen). Fettschrift bedeutet, dass der Text genau so eingegeben werden muss, austauschbare Argumente werden durch Kursivschrift gekennzeichnet. Klammern ([]) umgeben optionale Argumente, senkrechte Striche (|) trennen Elemente, von denen eines auszuwählen ist, und Ellipsen (…) können wiederholt werden. Für Funktionen enthält er die Deklarationen aller erforderlichen Daten oder #include-Anweisungen, gefolgt von der Funktionsdeklaration.

Wenn ein Feature-Test-Makro definiert werden muss, um die Deklaration einer Funktion (oder einer Variable) aus einer Header-Datei zu erhalten, dann sollte das in SYNOPSIS angegeben werden. Wie es gemacht wird, ist in feature_test_macros(7) beschrieben.

CONFIGURATION

Konfigurationsdetails für ein Gerät

Dieser Abschnitt kommt in der Regel nur in Seiten aus Abschnitt 4 vor.

DESCRIPTION

Eine Bescheibung der Funktionsweise des Programms, der Funktion oder des Formats

Legen Sie die Interaktion mit Dateien und der Standardeingabe dar und was in der Standardausgabe oder der Standardfehlerausgabe ausgegeben wird. Lassen Sie Interna und Details der Implementierung aus, wenn sie nicht entscheidend für das Verständnis der Schnittstelle sind. Beschreiben Sie den üblichen Fall, für Informationen über Befehlszeilenoptionen eines Programms verwenden Sie den Abschnitt OPTIONS.

Achten Sie darauf, bei der Beschreibung eines neuen Verhaltens oder eines neuen Schalters für einen Systemaufruf oder eine Bibliotheksfunktion die Kernel- oder C-Bibliotheksversion anzugeben, bei der diese Änderung eingeführt wurde. Die bevorzugte Methode, auf diese Information hinzuweisen, ist bei Schaltern als Teil einer .TP-Liste, in der folgenden Form (hier für einen neuen Schalter eines Systemaufrufes):

Die Versionsinformation anzugeben ist besonders hilfreich für Benutzer, die auf eine ältere Kernel- oder C-Bibliotheksversion angewiesen sind (dies ist zum Beispiel bei eingebetteten Systemen typisch).

OPTIONS

Eine Beschreibung der von einem Programm akzeptierten Befehlszeilenoptionen und wie sie das Verhalten des Programms verändern.

Dieser Abschnitt sollte nur in Handbuchseiten der Abschnitte 1 und 8 enthalten sein.

EXIT STATUS

Eine Liste der möglichen Werte für den Exit-Status eines Programms und die Umstände, die zur Rückgabe dieser Werte führen

Dieser Abschnitt sollte nur in Handbuchseiten der Abschnitte 1 und 8 enthalten sein.

RETURN VALUE

Dieser Abschnitt enthält für Handbuchseiten aus den Abschnitten 2 und 3 die Rückgabewerte der Bibliotheksroutine für die aufrufende Routine und erläutert die Bedingungen, die zu einem bestimmten Rückgabewert führen.

ERRORS

Dieser Abschnitt enthält für Handbuchseiten aus den Abschnitten 2 und 3 mögliche Werte, die im Fehlerfall in errno platziert werden und erläutert mögliche Ursachen der Fehler.

Wenn mehrere unterschiedliche Umstände den gleichen Fehler erzeugen, wird bevorzugt, dass verschiedene Listeneinträge (mit gedoppelten Fehlernamen) für jeden dieser Umstände erstellt werden. Dadurch werden die unterschiedlichen Umstände deutlicher, die Liste einfacher zu lesen und dies erlaubt es, Metainformationen (z.B. Kernelversionsnummern, unter denen die Umstände erstmals zum Tragen kamen) leichter für jeden Umstand zu markieren.

Die Fehlerliste sollte alphabetisch sortiert sein.

ENVIRONMENT

Eine Liste aller Umgebungsvariablen, die auf das Programm einwirken mit Erläuterung, was sie bewirken.

FILES

Eine Liste aller Dateien, die das Programm oder die Funktion verwenden, wie Konfigurationsdateien, Einrichtungsdateien und Dateien, auf denen das Programm direkt arbeitet

Geben Sie den vollständigen Pfadnamen dieser Dateien an und nutzen Sie den Installationsprozess, um den Verzeichnisteil des Pfades an die Benutzereinstellungen anzupassen. Für viele Programme ist als Installationsverzeichnis /usr/local voreingestellt. Ihre grundlegende Handbuchseite sollte daher /usr/local als Basis verwenden.

ATTRIBUTES

Eine Zusammenfassung der verschiedenen Attribute von Funktionen, die auf dieser Seite dokumentiert sind. Siehe attributes(7) für weitere Details.

VERSIONS

Hier steht eine kurze Zusammenfassung der Linux-Kernel- oder Glibc-Versionen, in denen ein Systemaufruf oder eine Bibliotheksfunktion erschien oder das Verhalten wesentlich veränderte.

Als allgemeine Regel gilt, dass jede neue Schnittstelle einen VERSIONS-Abschnitt in der Handbuchseite enthalten sollte. Leider verfügen viele bestehende Handbuchseiten nicht über diese Informationen (da es dafür keine entsprechende Richtlinie gab, als sie geschrieben wurden). Patches zur Ergänzung dieser Abschnitte sind willkommen. Aus der Sicht von Programmierern, die neuen Code schreiben, werden diese Informationen wohl nur für Kernel-Schnittstellen interessant sein, die in Linux 2.4 oder später hinzugefügt wurden, und für geänderte Bibliotheksfunktionen in der Glibc seit Version 2.1. (d. h. also Änderungen seit Kernel 2.2 und Glibc 2.0).

Auch die Handbuchseite über Systemaufrufe (syscalls(2)) enthält Informationen über die Kernel-Versionen, in denen bestimmte Systemaufrufe erstmals vorkamen.

CONFORMING TO

Eine Beschreibung aller Standards oder Konventionen, die die Funktionen oder den Befehle betrifft, die durch die Handbuchseite beschrieben wird.

Die bevorzugten Ausdrücke für die verschiedenen Standards sind als Überschriften in standards(7) aufgeführt.

Für eine Handbuchseite in Abschnitt 2 oder 3 sollte(n) hier die POSIX.1-Version(en) stehen, denen der Aufruf entspricht. Auch sollte angegeben werden, ob der Aufruf in C99 beschrieben ist. (Sorgen Sie sich nicht zu sehr um andere Standards wie SUS, SUSv2 und XPG oder die SVr4- und 4.xBSD-Implementierungsstandards, es sei denn, der Aufruf wurde in diesen Standards beschrieben, ist aber nicht in der aktuellen Version von POSIX.1 enthalten.)

Wenn der Aufruf von keinen Standards geregelt ist, aber allgemein auf anderen Systemen vorhanden ist, erwähnen Sie diese Systeme. Wenn der Aufruf Linux-spezifisch ist, erwähnen Sie auch das.

Wenn dieser Abschnitt nur aus einer Liste von Standards besteht (das ist üblicherweise der Fall), beenden Sie die Liste mit einem Punkt ('.').

NOTES

Verschiedene Anmerkungen

Für Handbuchseiten der Abschnitte 2 und 3 könnten die Aufnahme von Unterabschnitten (SS) Linux Notes und Glibc Notes nützlich sein.

In Abschnitt 2 verwenden Sie die Überschrift C library/kernel differences, um Abschnitte zu markieren, die die Unterschiede (falls vorhanden) zwischen der C-Bibliothek-Wrapper-Funktion für einen Systemaufruf und der rohen Systemaufrufschnittstelle durch den Kernel beschreiben.

BUGS

Eine Liste von Einschränkungen, bekannten Mängeln oder Unannehmlichkeiten und weiteren fragwürdigen Verhalten.

EXAMPLE

Ein oder mehrere Beispiele für die Anwendung der Funktion, der Datei oder des Befehls

Wie Beispielprogramme geschrieben werden sollten, beschreibt der Abschnitt Beispielprogramme weiter unten.

AUTHORS

Eine Liste der Autoren der Dokumentation oder des Programms

Von einem AUTHORS-Bereich wird entschieden abgeraten. Allgemein ist es besser, nicht jede Seite mit einer Liste von (im Laufe der Zeit potenziell zahlreichen) Autoren vollzustopfen. Wenn Sie eine Seite schreiben oder signifikant verändern, fügen Sie einen Copyright-Vermerk als Kommentar in die Quelldatei ein. Wenn Sie der Autor eines Gerätetreibers sind und eine Adresse für das Melden von Fehlern angeben wollen, tun Sie das im Abschnitt FEHLER.

SEE ALSO

Eine durch Kommata gegliederte Liste thematisch verwandter Handbuchseiten; manchmal folgen weitere Handbuchseiten oder Dokumente mit inhaltlichem Bezug

Die Liste sollte nach Abschnittsnummern und in den Abschnitten alphabetisch sortiert werden. Schließen Sie die Liste nicht mit einem Punkt ab.

Wenn die »SEE ALSO«-Liste viele lange Namen von Handbuchseiten enthält, kann es zur Verbesserung der visuellen Darstellung sinnvoll sein, die Anweisungen .ad l (nicht rechts anordnen) und .nh (keine Silbentrennung) zu verwenden. Die Silbentrennung individueller Seitennamen können Sie vermeiden, indem Sie den Wörtern die Zeichenkette »\%« voranstellen.

Aufgrund der autonomen und verteilten Natur von FOSS-Projekten und ihrer Dokumentation ist es manchmal notwendig – und in vielen Fällen wünschenswert –, dass der Abschnitt »SIEHE AUCH« Referenzen auf Handbuchseiten von anderen Projekten enthält.

Geschlechtsneutrale Begriffswahl¶

Konventionen für die Formatierung von Handbuchseiten, die Befehle beschreiben¶

Der Name des Befehls und seine Optionen sollten stets fett formatiert werden.

Konventionen für die Formatierung von Handbuchseiten, die Funktionen beschreiben¶

int meineFunktion(int argc, char **argv);

Variablennamen sollten wie die Namen von Argumenten kursiv geschrieben werden.

Jeder Hinweis auf den Gegenstand der aktuellen Handbuchseite sollte mit diesem Namen in Fettschrift geschrieben werden, gefolgt von einem Paar Klammern in Normalschrift (Roman). Zum Beispiel würden in der Handbuchseite von fcntl(2) Verweise auf das Thema der Seite als fcntl() geschrieben werden. Die empfohlene Schreibweise in der Quelldatei ist

    .BR fcntl ().

Die Verwendung dieses Formats anstatt »\fB…\fP()« erleichtert die Entwicklung von Werkzeugen für die Auswertung von Handbuch-Quelltexten.

Semantische Zeilenvorschübe verwenden ¶

Formatierungskonventionen (Allgemeines)¶

Dateinamen (ob Pfadnamen oder Verweise auf Header-Dateien) werden immer kursiv gesetzt (z. B. <stdio.h>), außer in der SYNOPSIS, wo eingefügte Dateien fett geschrieben werden (z. B. #include <stdio.h>). Wenn Sie auf die Einbindung einer Standard-Header-Datei verweisen, setzen Sie die Header-Datei wie in C gebräuchlich in spitze Klammern (z.B. <stdio.h>).

Spezielle Makros, die in der Regel mit Großbuchstaben geschrieben werden, werden in Fettdruck gesetzt (z.B. MAXINT). Ausnahme: Schreiben Sie NULL nicht fett.

Bei der Aufzählung einer Liste von Fehlercodes werden die Codes in Fettschrift geschrieben. (Diese Liste verwendet in der Regel das Makro .TP.)

Vollständige Befehle sollten, wenn sie lang sind, eine eigene, eingerückte Zeile bekommen, der eine Leerzeile vor- und nachgestellt wird, zum Beispiel:

man 7 man-pages

Kurze Befehle können, kursiv gesetzt, in den laufenden Text aufgenommen werden; z. B. man 7 man-pages. In diesem Fall kann es sich lohnen, an geeigneten Stellen in der Befehlszeile geschützte Leerzeichen ("\ ") zu verwenden. Befehlsoptionen sollten kursiv geschrieben werden (z. B. -l).

Ausdrücke sollten kursiv gesetzt werden, wenn Sie nicht auf einer separaten Zeile eingerückt geschrieben werden. Auch hier kann die Verwendung von geschützten Leerzeichen angezeigt sein, wenn der Ausdruck in den Fließtext integriert ist.

Bei der Angabe von Shell-Sitzungen sollte die Benutzereingabe stets fett formatiert werden, bespielsweise

$ date
Do Jul  7 13:01:27 CEST 2016

Jeder Verweis auf eine andere Handbuchseite sollte den Namen in Fettschrift darstellen und immer ohne Leerzeichen von der Nummer des Abschnitts in Normalschrift (Roman) gefolgt werden; (z. B. intro(2)). Die empfohlene Schreibweise in der Quelldatei ist

    .BR intro (2).

(Die Angabe der Abschnittsnummer in Querverweisen ermöglicht es Werkzeugen wie man2html(1), korrekte Hyperlinks zu erstellen.)

Steuerzeichen sollten in Fettschrift ohne Anführungszeichen geschrieben werden, beispielsweise ^X.

Rechtschreibung¶

Abgesehen von den gut bekannten Rechtschreibunterschieden gibt es ein paar weitere Feinheiten, auf die Sie achten sollten:

*

Amerikanisches Englisch tendiert zu den Formen »backward«, »upward«, »toward« und so weiter, während im britischen Englisch eher »backwards«, »upwards«, »towards«, und so weiter verwendet werden.

BSD-Versionsnummern¶

Großschreibung¶

    .SS Unicode under Linux

Einzug bei Strukturdefinitionen, Protokollen von Shell-Sitzungen und so weiter.¶

    .PP
    .in +4n
    .EX
    int
    main(int argc, char *argv[])
    {
        return 0;
    }
    .EE
    .in
    .PP

Bevorzugte Begriffe¶

Siehe auch den nachfolgenden Abschnitt Bindestriche in attributiven Zusammensetzungen.

Zu vermeidende Ausdrücke¶

Geschützte Marken¶

DG/UX HP-UX UNIX UnixWare

NULL, NUL, Null-Zeiger und Null-Zeichen¶

Der bevorzugte Begriff für den Zeiger ist »null pointer« oder einfach »NULL«, bitte schreiben Sie nicht »NULL pointer«.

Der bevorzugte Begriff für das Byte ist »null byte«. Bitte schreiben Sie nicht »NUL«, da es zu leicht mit »NULL« verwechselt werden kann. Vermeiden Sie auch die Begriffe »zero byte« und »null character«. Das Byte, das eine C-Zeichenkette beendet, sollte als »the terminating null byte« beschrieben werden. Zeichenketten können als »null-terminated« bezeichnet werden, vermeiden Sie dagegen »NUL-terminated«.

Hyperlinks¶

BROWSER=firefox man -H Seitenname

Verwendung von e.g., i.e., etc., a.k.a. und ähnlichem¶

Die einzige Stelle, wo solche Abkürzungen akzeptabel sind, ist in kurzen in Klammern gesetzten Anmerkungen (z.B. wie in dieser hier).

Verwenden Sie stets Punkte in solchen Abkürzungen, wie hier gezeigt. Zusätzlich sollte auf »e.g.« und »i.e.« stets ein Komma folgen.

Em-Gedankenstriche¶

Bindestriche in attributiven Zusammensetzungen¶

32-bit value command-line argument floating-point number run-time check user-space function wide-character string

Zusammensetzungen mit multi, non, pre, re, sub, usw.¶

interprocess multithreaded multiprocess nonblocking nondefault nonempty noninteractive nonnegative nonportable nonzero preallocated precreate prerecorded reestablished reinitialize rearm reread subcomponent subdirectory subsystem

Bindestriche sollten gesetzt werden, wenn die Präfixe in Wörtern verwendet werden, die nicht zum englischen Standardwortschatz gehören, wie geschützte Marken, Eigennamen, Akronyme oder zusammengesetzte Begriffe. Einige Beispiele:

non-ASCII non-English non-NULL non-real-time

Beachten Sie auch, dass »re-create« und »recreate« zwei Verben unterschiedlicher Bedeutung sind. Das erstere dürfte vermutlich jenes sein, was Sie benötigen.

Echtes Minuszeichen¶

\-

Diese Richtlinie gilt auch für Code-Beispiele.

Zeichenkonstanten¶

\(aqC\(aq

wobei C das zitierte Zeichen ist. Diese Richtlinie ist auch auf Zeichenkonstanten und in code-Beispielen anzuwenden.

Beispielprogramme und Shell-Sitzungen¶

• Beispielprogramme sollten in C geschrieben sein.
• Ein Beispielprogramm ist nur dann notwendig und sinnvoll, wenn es inhaltlich weiter geht als das, was leicht in einer Textbeschreibung der Schnittstelle bereitgestellt werden kann. Ein Beispielprogramm, das nichts Anderes tut, als eine Schnittstelle aufzurufen, hat in der Regel wenig Sinn.
• Beispielprogramme sollten eher kurz sein (vorzugsweise weniger als 100 Zeilen, idealerweise weniger als 50 Zeilen).
• Beispielprogramme sollten nach dem Aufruf von System- und Bibliotheksfunktionen prüfen, ob Fehler aufgetreten sind.
• Beispielprogramme sollten vollständig sein und keine Warnungen ausgeben, wenn sie mit cc -Wall kompiliert werden.
• Soweit möglich und angebracht, sollten Beispielprogramme Experimente ermöglichen, wie sich ihr Verhalten durch Variation der Eingabe verändert (idealerweise mittels Befehlszeilenargumenten oder alternativ durch vom Programm gelesene Eingaben).
• Beispielprogramme sollten im Stil von Kernighan und Ritchie (mit Einzügen von 4 Leerzeichen) verfasst werden. (Verwenden Sie in Quelltexten keine Tabulatoren!) Der folgende Befehl kann dazu verwandt werden, Ihren Quellcode ähnlich dem bevorzugten Stil zu formatieren:

indent -npro -kr -i4 -ts4 -sob -l72 -ss -nut -psl prog.c

*

Aus Konsistenzgründen sollten alle Beispielprogramm mit einer der folgenden Sequenzen beendet werden:

exit(EXIT_SUCCESS); exit(EXIT_FAILURE);

Vermeiden Sie die folgenden Formen, um ein Programm zu beenden:

exit(0); exit(1); return n;

*

Falls ein umfangreicher erklärender Text vor dem Programm-Quellcode steht, markieren Sie den Quellcode mit der Zwischenüberschrift Program source, wie in:

.SS Program source

Tun Sie dies immer, wenn der erklärende Text ein Sitzungsprotokoll der Shell enthält.

Wenn Sie eine Shell-Sitzung einfügen, welche die Verwendung eines Programms oder andere Möglichkeiten des Systems demonstriert:

• Setzen Sie das Sitzungsprotokoll vor die Quellcode-Auflistung.
• Rücken Sie das Sitzungsprotokoll um vier Zeichen ein.
• Wählen Sie Fettschrift für vom Benutzer eingegebenen Text, um ihn von der vom System erzeugten Ausgabe zu unterscheiden.

In wait(2) und pipe(2) finden Sie vorbildliche Beispielprogramme.