19.4 Liste der Funktionen

In diesem Abschnitt werden die Funktionen aus der Standardbibliothek von ANSI-C aufgelistet.

Nach der Angabe der #include -Datei, in der die jeweilige Funktion deklariert ist, und der Deklaration selbst, wird die Funktion vorgestellt. Soweit vorhanden, werden Parameter und Rückgabewert angegeben.

Von Fall zu Fall wird ein kleines Verwendungsbeispiel angegeben.

Die Funktionen sind alphabetisch sortiert.

Alle Funktionen, die in einer tatsächlichen Implementation vorhanden sind, aber hier nicht oder mit einer anderen Funktionsweise genannt sind, sollten so weit als möglich vermieden werden, da der Quelltext dann nicht mehr portierbar ist.

Müssen solche Funktionen unbedingt verwendet werden, sollte man darauf achten, daß sie nur in wenigen, möglichst übersichtlichen Teilen des Programms vorkommen und von der eigentlichen Programmlogik möglichst weit getrennt werden. Das Abtrennen vom eigentlichen Programm und deutliches Kommentieren aller Abweichungen vom ANSI-Standard erleichtert ein späteres Übertragen sowie Einarbeiten fremder Personen enorm. Für spätere Portierungen ist es außerdem sehr hilfreich, wenn bei zusätzlichen Funktionen, die nicht standardisiert sind, als Kommentar die genaue Funktionsweise oder eine entsprechende Literaturangabe im Quelltext erscheint. Sonst kann es passieren, daß die Funktion auf einem anderen System nicht existiert und nachgebildet werden muß, aber niemand mehr so genau weiß, was die Funktion eigentlich macht.

abort()

#include <stdlib.h>

void abort( void );

bricht das Programm unmittelbar ab.

Funktionen, die mit atexit() eingetragen wurden, werden nicht ausgeführt; offene Dateien werden nicht geschlossen oder ihre Puffer ausgeschrieben; temporäre Dateien (mit tmpfile() geöffnet) werden nicht gelöscht. Das Signal SIGABRT wird mit raise( SIGABRT ) erzeugt und das Programm dann mit dem Rückgabewert 3 abgebrochen.

$\rightarrow$exit(), raise(), assert()

abs()

#include <stdlib.h>

int abs( int wert );

gibt den Absolutbetrag von wert zurück.

$\rightarrow$labs(), fabs()

acos()

#include <math.h>

double acos( double argument );

liefert den ersten Wert des $\arccos(\tt argument)$ im Bogenmaß (im Bereich 0.0... $\pi$). argument muß dazu im Bereich -1.0...+1.0 liegen. Ansonsten wird 0.0 zurückgegeben und errno wird auf EDOM gesetzt.

$\rightarrow$cos(), asin(), atan(), atan2()

asctime()

#include <time.h>

char *asctime( const struct tm *tm_zeiger );

liefert einen Zeiger auf einen String, der die Zeit in *tm_zeiger beschreibt. Beispielsweise liefert das Programm

#include <time.h>
#include <stddef.h>             /* wegen NULL                 */

main()
{
    time_t      t;

    t = time( NULL );       /* Die Uhrzeit des Rechners lesen */

    /* Die aktuelle Zeit in eine struct tm verwandeln,
     * von da in einen String und ausgeben
     */
    printf( "es ist jetzt %s",
            asctime( localtime( &t ) ) );
    printf( "ok.\n" );
}

die aktuelle Uhrzeit in der Form

es ist jetzt Mon Mar 11 20:37:20 1991
ok.

Eine für hiesige Gewohnheiten gefälligere Form der Zeitdarstellung wird auf Seite vorgeführt.

Die Positionen der einzelnen Felder in dem 26 Zeichen langen String sind immer gleich und der String ist mit \n und \0 beendet.

Platz für den String braucht nicht bereitgestellt zu werden, sondern ist statisch in der Funktion asctime() vorhanden und wird beim nächsten Aufruf derselben oder ctime() überschrieben.

$\rightarrow$ctime(), strftime(), mktime(), time()

asin()

#include <math.h>

double asin( double argument );

liefert den ersten Wert des $\arcsin(\tt argument)$ im Bogenmaß (im Bereich $-\pi / 2 \ldots +\pi / 2$). argument muß dazu im Bereich -1.0...+1.0 liegen. Ansonsten wird 0.0 zurückgegeben und errno wird auf EDOM gesetzt.

$\rightarrow$sin(), acos(), atan(), atan2()

assert()

#include <assert.h>

void assert( int ausdruck );

ist ein Makro zur Fehlersuche während der Programmentwicklung.

Wenn vor der Praeprozessoranweisung #include <assert.h> die Anweisung

#define NDEBUG

steht, dann wird assert() vom Praeprozessor aus dem Programm entfernt und bewirkt nichts.

Ansonsten wird vom Praeprozessor ein Stück Quelltext so erzeugt, daß der ausdruck ausgewertet wird und im Falle von 0 bzw. logisch falsch wird eine Meldung in der Form

assertion ausdruck failed: file Dateiname line Zeilennummer

ausgegeben und anschließend das Programm mit abort() abgebrochen.

Siehe auch die Funktion abort().

Ein Beispiel zur Verwendung von assert() ist in Fehlersuche mit Standard-C zu finden.

$\rightarrow$abort(), exit()

atan()

#include <math.h>

double atan( double argument );

liefert den ersten Wert von $\arctan(\tt argument)$ im Bogenmaß (im Bereich $-\frac{\pi}{2}\ldots+\frac{\pi}{2}$).

$\rightarrow$tan(), asin(), acos(), atan2()

atan2()

#include <math.h>

double atan2( double zaehler, double nenner );

liefert den ersten Wert des $\arctan(\frac{\tt zaehler}{\tt nenner})$ im Bogenmaß (im Bereich $-\pi$ $\ldots$ $+\pi$).

zaehler und nenner dürfen dabei nicht beide den Wert 0.0 haben; in diesem Fall wird errno auf EDOM gesetzt und 0.0 zurückgegeben.

$\rightarrow$tan(), asin(), acos(), atan()

atexit()

#include <stdlib.h>

int atexit( void ( *funktion_zeiger )( void );

sorgt dafür, daß bei einem normalen Programmende ( return in main() oder exit()) die Funktion, auf die funktion_zeiger zeigt, aufgerufen wird. *funktion_zeiger erhält keinen Parameter und liefert keinen Rückgabewert. Werden mehrere Funktionen so installiert, dann werden sie bei Programmende entgegen ihrer Installationsreihenfolge ausgeführt. Zu diesem Zeitpunkt existieren keine automatischen Variablen mehr, aber offene Dateien und temporäre Dateien sind noch verwendbar.

Wird das Programm mit abort() beendet, dann werden die mit atexit() installierten Funktionen nicht ausgeführt.

Rückgabewert ist ungleich 0, wenn zuviele Einträge mit atexit() installiert wurden.

Beispielaufruf:

/* fuassert.c 30. 7.95 kw
 */

#include <stdlib.h>

void erste( void )
{
  printf( "Hallo, hier ist die erste!\n" );
}

void zweite( void )
{
  printf( "Hallo, hier ist die zweite!\n" );
}

int main()
{
  /* die beiden obigen Funktionen installieren,
   * damit sie bei Programmende aufgerufen werden:
    */
  atexit( &erste );
  atexit( &zweite );

  /* Jetzt koennte das Programm irgendetwas tun ...
   */
  printf( "irgendetwas tun ...\n" );

  /* ... und dann beenden.
   * Nach diesem return werden die mit atexit()
   * installierten Funktionen in umgekehrter
   * Reihenfolge ausgefuehrt:
   */
  return 0;
}

Ausgabe davon:

irgendetwas tun ...
Hallo, hier ist die zweite!
Hallo, hier ist die erste!

$\rightarrow$exit(), abort()

atof()

#include <stdlib.h>

double atof( const char *string );

verwandelt string soweit möglich in eine double ; dabei wird beim ersten Zeichen in string abgebrochen, das nicht als Bestandteil einer Gleitkommazahl interpretiert werden kann. Kann überhaupt kein Zeichen umgewandelt werden, dann wird 0.0 zurückgegeben.

Die Funktion atof() sollte für Neuentwicklungen nicht mehr verwendet werden. Sie ist nur zur Kompatibilität mit älteren C-Versionen vorhanden und kann durch strtod( string, NULL ) ersetzt werden.

Wenn der Wertebereich von double nicht ausreicht, um das Ergebnis der Umwandlung darzustellen, dann ist der Rückgabewert unbestimmt.

$\rightarrow$strtod(), atoi(), atol(), sscanf()

atoi()

#include <stdlib.h>

int atoi( const char *string );

verwandelt string soweit möglich in eine int ; dabei wird beim ersten Zeichen in string abgebrochen, das nicht als Bestandteil einer ganzen Zahl interpretiert werden kann. Kann überhaupt kein Zeichen umgewandelt werden, dann wird 0 zurückgegeben.

Die Funktion atoi() sollte für Neuentwicklungen nicht mehr verwendet werden. Sie ist nur zur Kompatibilität mit älteren C-Versionen vorhanden und kann durch

(int)strtol( string, NULL, 10 )

ersetzt werden.

Wenn der Wertebereich von int nicht ausreicht, um das Ergebnis der Umwandlung darzustellen, dann ist der Rückgabewert unbestimmt.

$\rightarrow$strtol(), atof(), atol(), sscanf()

atol()

#include <stdlib.h>

long int atol( const char *string );

verwandelt string soweit möglich in eine long int ; dabei wird beim ersten Zeichen in string abgebrochen, das nicht als Bestandteil einer ganzen Zahl interpretiert werden kann. Kann überhaupt kein Zeichen umgewandelt werden, dann wird 0L zurückgegeben.

Die Funktion atol() sollte für Neuentwicklungen nicht mehr verwendet werden. Sie ist nur zur Kompatibilität mit älteren C-Versionen vorhanden und kann durch strtol( string, NULL, 10 ) ersetzt werden.

Wenn der String eine zu große Zahl für den Wertebereich von long int ergibt, dann ist das Ergebnis nicht definiert und errno wird zu ERANGE gesetzt.

$\rightarrow$atoi(), atof(), sscanf()

bsearch()

#include <stdlib.h>

void *bsearch( const void *suchschluessel,
               const void *feldanfang,
               size_t     elemente,
               size_t     elementgroesse,
               int ( *vergleichsfunktion )( const void *e1,
                                            const void *e2  )
             );

sucht in einem Feld nach einem Element, das den Wert (*suchschluessel) hat und liefert einen Zeiger auf dieses Element, wenn folgende Bedingungen erfüllt sind:

• Das Feld beginnt an der Stelle feldanfang im Speicher.
• Das Feld hat (elemente) Elemente jeweils der Größe (elementgroesse) .
• vergleichsfunktion zeigt auf eine Funktion, die zwei Zeiger auf je ein Feldelement entgegennimmt und einen negativen int -Wert liefert, wenn der erste Parameter auf ein Element mit kleinerem Suchschlüssel zeigt als der zweite Parameter, 0 liefert, wenn beide Parameter auf Elemente mit gleich großem Suchschlüssel zeigen und sonst einen positiven Wert liefert.
• Das Feld ist gemäß den Kriterien der vergleichsfunktion aufsteigend sortiert.

Trifft (*suchschluessel) auf keines der Elemente im Feld zu, dann liefert bsearch() den Wert NULL .

Trifft (*suchschluessel) auf mehrere Feldelemente zu, dann wird eines davon geliefert; aber es kann nicht vorhergesagt werden, welches.

Das folgende Beispiel liest einige Vor- und Nachnamen ein und sortiert sie nach den Vornamen. Dann kann der Benutzer einen Vornamen eingeben, zu dem der Nachname gesucht wird:

/* fubsear.c 30. 7.95 kw
 */

#include <stdlib.h>
#include <stdio.h>
#include <string.h>

#define         NP      5

/* Datentyp, um einen Vor- und einen Nachnamen zu speichern:
 */
typedef struct
{
  char    vorname[30];
  char    nachname[30];
}
person_t;

/* davon ein Feld:
 */
person_t        personfeld[NP];

/* vergleicht fuer qsort() oder bsearch() zwei Feldelemente
 * (nach Vornamen):
 */
int vergl_vn( const void *p1, const void *p2 )
{
  return strcmp( ((person_t *)p1)->vorname,
                 ((person_t *)p2)->vorname
                 );
}

int main()
{
  int         i;
  person_t
    vergleichsperson,
    *gefunden;

  /* Personen einlesen:
   */
  for( i=0; i<NP; i++ )
  {
    printf( "Bitte den Vornamen:  " );
    scanf( "%s", personfeld[i].vorname );
    printf( "Bitte den Nachnamen: " );
    scanf( "%s", personfeld[i].nachname );
  }

  /* Nach Vornamen sortieren:
   */
  qsort( personfeld, NP, sizeof(person_t), vergl_vn );

  /* Nach einem Vornamen fragen und die Person suchen:
   */
  printf( "Bitte einen Vornamen:  " );
  scanf( "%s", vergleichsperson.vorname );
  gefunden = bsearch( &vergleichsperson,
                      personfeld,
                      NP,
                      sizeof(person_t),
                      vergl_vn
                      );
  if( NULL==gefunden )
  {
    puts( "Den kann ich nicht finden!" );
  }
  else
  {
    printf( "%s %s\n",
            gefunden->vorname,
            gefunden->nachname );
  }

  return 0;
}

Bei älteren, nicht ANSI-konformen Compilern kann es sein, daß die Anweisung

        gefunden = bsearch( &vergleichsperson,
                            personfeld,
                            NP,
                            sizeof(person_t),
                            vergl_vn             );

geändert werden muß zu:

        gefunden = bsearch( &vergleichsperson,
                            personfeld,
                            NP,
                            sizeof(person_t),
                            &vergl_vn            );

(siehe dazu Zeiger auf Funktionen).

$\rightarrow$qsort()

calloc()

#include <stdlib.h>

void *calloc( size_t wieviele, size_t wiegross );

versucht, einen Speicherblock mit (wieviele*wiegross) Bytes zu reservieren. Der reservierte Speicher wird in ganzer Länge auf den Wert 0 gesetzt.

Rückgabewert ist ein Zeiger auf den Anfang des reservierten Blocks, wenn alles gut ging, oder der NULL -Zeiger, wenn kein Block ausreichender Größe zu haben ist.

$\rightarrow$free(), malloc(), realloc()

ceil()

#include <math.h>

double ceil( double wert );

liefert die nächstgrößere ganze Zahl zu wert als double .

Beispiel:

#include <math.h>

int main()
{
  double  d;

  for( d=-2.0; d<2.0; d+=0.2 )
    printf( "ceil(%f) = %f\n", d, ceil(d) );
}

Dieses Programm liefert die Ausgabe:

ceil(-2.000000) = -2.000000
ceil(-1.800000) = -1.000000
ceil(-1.600000) = -1.000000
ceil(-1.400000) = -1.000000
ceil(-1.200000) = -1.000000
ceil(-1.000000) = -1.000000
ceil(-0.800000) = -0.000000
ceil(-0.600000) = -0.000000
ceil(-0.400000) = -0.000000
ceil(-0.200000) = -0.000000
ceil(0.000000) = 1.000000
ceil(0.200000) = 1.000000
ceil(0.400000) = 1.000000
ceil(0.600000) = 1.000000
ceil(0.800000) = 1.000000
ceil(1.000000) = 2.000000
ceil(1.200000) = 2.000000
ceil(1.400000) = 2.000000
ceil(1.600000) = 2.000000
ceil(1.800000) = 2.000000

$\rightarrow$floor()

clearerr()

#include <stdio.h>

void clearerr( FILE *datei );

löscht gegebenenfalls die Indikatoren für Dateifehler und Dateiende für die übergebene Datei.

clearerr() kann auch als Makro definiert sein.

$\rightarrow$feof(), ferror(), fopen(), freopen(), fclose(), rewind()

clock()

#include <time.h>

clock_t clock( void );

liefert die Anzahl der ,,Schläge`` der internen Rechneruhr seit Programmbeginn.

Dies ist ein Maß für die Zeit, die das Programm bereits im Rechner läuft.

Die Anzahl der Uhrschläge pro Sekunde ist mit dem Makro CLOCKS_PER_SEC definiert. Zur Umrechnung des Funktionsergebnisses von clock() in Sekunden kann man das Funktionsergebnis deshalb durch CLOCKS_PER_SEC teilen³⁷.

Je nach Rechnersystem kann man nicht sicher sein, daß diese Funktion funktioniert, da die Zeitinformation nicht immer zur Verfügung steht. Dann liefert clock() immer den Wert -1.

Beispiel:

/* fuclock.c 30. 7.95 kw
 */

#include <time.h>
#include <stdio.h>

int main()
{
  clock_t
    start,
    ende;
  long int  i;
  char      name[30];

  start = clock();

  if( -1==start )
  {
    puts( "Ich kann die Zeit nicht messen!" );
  }
  else
  {
    printf( "Bitte Ihren Namen eingeben: " );
    scanf( "%s", name );
    ende = clock();
    printf( "Sie brauchten %f sec fuer "
            "Ihren Namen, Sie %s!\n",
            (double)(ende-start)/CLOCKS_PER_SEC,
            name
            );
  }

  return 0;
}

$\rightarrow$time(), difftime()

cos()

#include <math.h>

double cos( double phi );

liefert den $\cos(\tt phi )$ ( phi ist im Bogenmaß anzugeben).

Ist phi betragsmäßig zu groß, dann kann das Ergebnis ungenau sein, ohne daß errno gesetzt wird.

$\rightarrow$acos(), sin(), tan(), cosh()

cosh()

#include <math.h>

double cosh( double phi );

liefert den $\cosh(\tt phi )$.

Ist phi betragsmäßig zu groß, dann wird der Wert HUGE_VAL zurückgegeben und errno auf ERANGE gesetzt.

$\rightarrow$cos(), sinh(), tanh()

ctime()

#include <time.h>

char *ctime( const time_t *zeit );

liefert einen Zeiger auf einen 26 Byte langen String (inkl. '\0' ), in dem die Kalenderzeit *zeit als Text beschrieben ist. Der String wird beim nächsten Aufruf von ctime() oder asctime() überschrieben.

ctime( zeit ) ist identisch mit asctime( localtime( zeit ) ) ; siehe dort.

$\rightarrow$asctime(), localtime(), time()

difftime()

#include <time.h>

double difftime( time_t zeit1, time_t zeit2 );

liefert die Differenz zwischen zwei Kalenderzeiten als double in der Einheit Sekunden. Wenn zeit2 vor zeit1 liegt, dann ist das Ergebnis negativ.

$\rightarrow$clock(), time()

div()

#include <stdlib.h>

div_t div( int dividend, int divisor );

führt die Division dividend/divisor aus und liefert eine Struktur mit zwei int -Elementen quot und rem . Das Element quot enthält das Ergebnis der ganzzahligen Division; rem enthält den Divisionsrest.

divisor darf nicht 0 sein.

$\rightarrow$ldiv(), fmod()

exit()

#include <stdlib.h>

void exit( int rueckgabe );

beendet das Programm, nachdem alle mit atexit() angemeldeten Funktionen ausgeführt wurden, alle offenen Dateien ordnungsgemäß geschlossen und alle temporären Dateien (siehe tmpfile()) gelöscht wurden.

An die Programmumgebung wird dann der Wert rueckgabe gemeldet. Ein Rückgabewert von 0 signalisiert allgemein, daß das Programm erfolgreich lief; andere Werte zeigen Fehler an. Dafür können auch die Werte EXIT_SUCCESS und EXIT_FAILURE aus stdlib.h verwendet werden.

$\rightarrow$abort(), atexit()

exp()

#include <math.h>

double exp( double wert );

liefert den Wert der Exponentialfunktion $({e}^\tt wert)$. Wenn wert zu groß ist, dann wird HUGE_VAL geliefert und errno auf ERANGE gesetzt.

$\rightarrow$log()

fabs()

#include <math.h>

double fabs( double wert );

liefert den Absolutbetrag von wert zurück.

$\rightarrow$abs(), labs()

fclose()

#include <stdio.h>

int fclose( FILE *datei );

schließt die übergebene Datei, nachdem die Puffer freigegeben wurden. Wurde die Datei mit tmpfile() erzeugt, dann wird sie gelöscht.

Wenn alles klappt, gibt die Funktion 0 zurück; ansonsten liefert sie EOF und setzt errno , um den Fehler näher zu beschreiben.

Beispiele stehen ab der Seite und auf der Seite .

$\rightarrow$fopen(), freopen(), tmpfile(), fflush()

feof()

#include <stdio.h>

int feof( FILE *datei );

testet den Indikator für das Dateiende der übergebenen Datei. Dieser Indikator kann mit rewind(), fsetpos(), fseek() oder clearerr() zurückgesetzt werden.

feof() liefert 0, wenn der Indikator für das Dateiende nicht gesetzt ist.

feof() kann als Makro definiert sein.

$\rightarrow$clearerr(), rewind(), fseek(), fsetpos()

ferror()

#include <stdio.h>

int ferror( FILE *datei );

Testet den Fehlerindikator der übergebenen Datei und liefert wahr, wenn selbiger gesetzt ist.

Der Indikator kann mit rewind() oder clearerr() gelöscht werden.

$\rightarrow$clearerr(), feof(), rewind()