Dokumentation von Funktionen in C
Das folgende Programm gibt eine mehr oder weniger zufällig ausgewählte int-Zahl zwischen »0« (einschließlich) und <stdlib.h> »RAND_MAX« (einschließlich) aus.
main.c#include <stdio.h> /* printf */
#include <stdlib.h> /* rand */int main( void )
{ printf
( "%d\n", rand() ); }stdout41
Die vordefinierten Funktionen der Programmiersprache C sind in der Spezifikation von C (ISO-Norm) beschrieben oder – wie man auch sagt – „dokumentiert“. Diese Dokumentation findet man daneben auch in C -Nachschlagewerken auf englisch oder auf deutsch, wie sie etwa in Buchform oder über Datennetze veröffentlicht werden.
Funktionen werden in C in etwa wie in dem folgenden Beispiel dokumentiert.
In der Dokumentation des Aufrufs »rand()« steht der Typ »int« dieses Aufrufs vor dem Namen der Funktion.
- Dokumentation von »rand()« (gekürzt und überarbeitet) [Synopse]
The rand function
Synopsis
#include <stdlib.h>
int rand(void);Description
The rand function returns a pseudo-random integer
integer number in the range 0 to RAND_MAX.- Dokumentation von »rand()« (gekürzt, überarbeitet und eingedeutscht)[Synopse]
Die Funktion rand
Synopse
#include <stdlib.h>
int rand(void);Beschreibung
Eine Pseudo-Zufallszahl zwischen 0 (einschliesslich)
und RAND_MAX (einschliesslich)
Die Dokumentation ist hier in englischer Sprache notiert, da sie üblicherweise auf Englisch geschrieben wird. Zur Erleichterung der Lektüre ist oben unter dieser Beschreibung aber eine deutschsprachige Übersetzung angegeben worden.
Die voranstehende Dokumentation gibt an, daß eine Übersetzungseinheit die #include -Direktive "#include <stdlib.h>" am Anfang der Übersetzungseinheit verwenden muß, wenn in der Übersetzungseinheit den Namen »rand« in dem in der Dokumentation beschriebenem Sinne verwendet werden soll.
Die Angabe der zu verwendenden Direktive und eine Kurzform der Angabe des Ergebnistyps der Funktion werden zusammen als „Synopse“ (englisch “synopsis ”) bezeichnet. Auch in der C -Norm wird der Begriff “synopsis ” für die beiden Zeilen verwendet, welche in der obigen Dokumentation unter dem Wort „Synopsis“ stehen.
Die Synopse zeigt ein Aufrufmuster "rand()" an, und gibt an, daß solch ein Aufruf einen Wert vom Datentyp "int" hat. Die Angabe »int« vor dem Namen »rand« besagt also, daß ein Aufrufausdruck dieser Funktion den Typ »int« hat. Dieser Typ wird manchmal auch Ergebnistyp der Funktion genannt.
Wir schreiben bis auf weiteres Typen (wie »int«) nicht in den Quelltext. Die Typen dienen uns hier lediglich zur Beschreibung von Funktionen.
Man nennt Funktionen, die wie »rand« einen Aufrufausdruck vom Datentyp »int« haben, auch als „eine int -Funktion“ und entsprechend Funktionen anderer Datentypen mit dem jeweiligen Datentyp ihres Aufrufausdrucks.
Das Wort "void" in den runden Klammern besagt, daß der Aufruf der Funktion mit leeren (engl.: void ) Klammern zu erfolgen hat, also wie in »rand()« oder »rand( )« (Leerraum in den Klammern ist erlaubt).
Traditionell wird solch eine Zeile oft mit einem Semikolon ";" abgeschlossen. Das heißt aber nicht, daß in einem Quelltext hinter solch einem Aufruf jedesmal ein Semikolon stehen muß.
Schließlich endet die Dokumentation mit einer Erklärung der Bedeutung von "rand()". Dabei wird erklärt, daß der Wert des Aufrufs dieser Funktion stets zwischen »0« (einschließlich) und dem Wert von »RAND_MAX« (einschließlich) liegt.
Man beachte, daß die Zeile »int rand();« nicht in einem Programm vorkommt, welches die Funktion <stdlib.h> »rand« aufruft. Die Dokumentation ist also nicht so zu verstehen, daß man sie in das Programm kopiert! Dokumentation darf nicht mit einem C -Programm verwechselt werden. Die Dokumentation ist nicht dafür gedacht, in ein C -Programm kopiert zu werden. Die Dokumentation ist dafür gedacht, bei Bedarf vom Programmierer gelesen zu werden.
Nicht aus der Dokumentation kopieren!
Ein Programmierer muß Dokumentationen von Funktionen verstehen, um dann die daraus gewonnenen Informationen zum Schreiben von Programmen verwenden zu können. Ein gelegentlicher Fehler von Anfängern, welche die Dokumentation noch nicht richtig verstehen, ist es, die Dokumentation einer Funktion in ein Programm zu kopieren. Dies ist in der Regel verkehrt.
Nicht aus der Dokumentation in den Quelltext kopieren!
Der folgende Text zeigt, wie es aussehen kann, wenn ein Anfänger einen Teil der Dokumentation in sein Programm kopiert, wie dies öfter beobachtet wurde. Anfänger, die so vorgehen sind danach meist nicht in der Lage, das entstandene Programm noch selbständig zu korrigieren. Daher sollte es grundsätzlich vermieden werden, einen Teil der Dokumentation in den Quelltext zu kopieren.
- Text
#include <stdio.h> /* printf */
#include <stdlib.h> /* rand */int main( void )
{ printf
( "%d\n", int rand(void); ); }- Konsole
main.c: In function 'main': main.c:3:35: error: expected expression before int { printf ( "%d\n", int rand(void); ); } ^- Konsole (übersetzt)
main.c: In der Funktion 'main': main.c:3:35: Fehler: Ausdruck vor int erwartet { printf ( "%d\n", int rand(void); ); } ^
(Der genaue Text solcher Fehlermeldungen hängt von der verwendeten C -Implementation ab.)
Schon zuvor wurde ja ein Programmbeispiel vorgestellt, das zeigt, wie die Funktion »rand« richtig aufgerufen wird. Wenn man sich das Programmieren durch Kopieren aus einer Vorlage erleichtern will, dann sollte man ein solches Beispielprogramm kopieren, aber nichts aus der Dokumentation!
Die Linux -Handbuchseite (Auszug)
Um die richtige Handbuchseite zu erhalten, ist die Angabe der Kennzahl des Abschnitts für die C-Funktionen, 3, nötig, da es zu »rand« auch noch in anderen Abschnitten des Linux -Handbuches Seiten gibt.
$ man 3 rand
RAND(3) Linux Programmer's Manual RAND(3)
NAME
rand, rand_r, srand - pseudo-random number generatorSYNOPSIS
#include <stdlib.h>
int rand(void);DESCRIPTION
The rand() function returns a pseudo-random integer in the range 0 to
RAND_MAX inclusive (i.e., the mathematical range [0, RAND_MAX]).- ...
Übungsfragen
⚠ Da die Auswahl an einfach aufrufbaren Funktionen an dieser Stelle des Kurses noch nicht so groß ist, werden in den Übungsaufgaben dieser und der folgenden Lektionen einige Funktionen als Beispiele verwendet, deren Sinn (Nutzen) nicht immer gut erkennbar ist. Der Leser sollte sich an dieser Stelle noch keine Gedanken darüber machen, wofür diese Funktionen gut sind ! Es geht zunächst nur darum, an (beliebigen) Beispielen zu erlernen, wie Funktionen aufgerufen werden.
Im folgenden findet sich die Dokumentation einer Funktion der Standardbibliothek.
- Dokumentation von »fegetround« (vereinfacht)
The fegetround function
Synopsis
#include <fenv.h>
int fegetround(void);Description
The fegetround function gets the current rounding direction.- Dokumentation von »fegetround« (übersetzt)
Die Funktion The fegetround
Synopse
#include <fenv.h>
int fegetround(void);Beschreibung
Die Funktion fegetround ergibt die momentane Richtung der Rundung.
⚠ Denken Sie jetzt nicht weiter über die Bedeutung der „Richtung der Rundung“ nach! Die Funktion »fegetround« dient hier nur als ein Beispiel, aber ihre genaue Bedeutung ist hier nicht wichtig. (Es handelt sich bei dieser Funktion um eine eher exotische Funktion, die man normalerweise selten braucht. Sie findet sich nur deshalb an dieser Stelle des Kurses, weil sie relativ leicht verwendbar ist.)
? Lesen von Dokumentation
Welchen Typ hat ein Aufruf der Funktion »fegetround«?
Welche Direktive wird am Anfang eines Programms benötigt, wenn der Bezeichner »fegetround« in jenem Programm verwendet werden soll?
Übungsaufgabe
/ Selbständiges Schreiben von Programmen
Schreiben Sie ein C -Programm, welches das Ergebnis eines Aufrufs der in der voranstehenden Übungsfrage behandelten Funktion »fegetround« ausgibt.
Übungsaufgabe
/ Selbständiges Arbeiten mit der Dokumentation
Schreiben Sie ein C -Programm, welches das Ergebnis eines Aufrufs der Funktion »getchar« ausgibt.
(Nach dem Start dieses Programms ist in dem Fenster, in welchem auch die Ausgaben des Programms angezeigt werden, einmal die Eingabetaste zu drücken, damit das Programm weiterläuft.)