SETBUF(3)

BEZEICHNUNG
setbuf, setvbuf - Stream-Puffer Funktionen

ÜBERSICHT
#include <stdio.h>

int setbuf( FILE *stream, char *buf);
void setbuffer(FILE *stream, char *buf, size_tsize);
void setlinebuf(FILE *stream);
int setvbuf( FILE *stream, char *buf, int mode , size_t size);

BESCHREIBUNG
Die drei Typen der verfügbaren Pufferungen sind nicht-gepuffert, block-gepuffert und zeilen-gepuffert. Wenn ein Ausgabe-Stream ungepuffert ist, erscheinen die Informationen in der Zieldatei oder auf dem Terminal direkt nachdem sie geschrieben wurden. Wenn die Ausgabe block-gepuffert ist, werden viele Zeichen erst einmal gesammelt und dann in einem Rutsch ausgegeben. Wenn die Ausgabe zeilen-gepuffert ist, werden die Zeichen bis zu einem Newline-Zeichen gesammelt und erst dann ausgegeben, oder Eingaben wurden von einem beliebigen Datenstrom gelesen, der mit dem Eingabegerät verbunden ist (üblicherweise stdin). Die Funktion fflush(3) darf dazu verwendet werden, ein Leeren des Puffers zu erzwingen. (Siehe auch fclose(3)) Normalerweise sind alle Dateien block-gepuffert. Wenn die erste I/O-Operation auf einer Datei durchgeführt wird, wird malloc(3) aufgerufen und ein Puffer wird angelegt. Wenn ein Datenstrom mit einem Terminal verbunden ist (wie stdout normalerweise), ist er zeilen-gepuffert. Der normale Fehlerstrom (stderr) ist per default immer nicht-gepuffert. Die Funktion setvbuf wird genutzt, um zu jedem beliebigen Zeitpunkt die Pufferung eines geöffneten Streams zu ändern. Als mode - Parameter wird einer der drei folgenden Konstanten verwendet:

    _IONBF
        Nicht gepuffert

    _IOLBF
        Zeilenpufferung

    _IOFBF
        Blockpufferung

Mit Ausnahme von ungepufferten Dateien sollte mit buf ein Zeiger auf einen Puffer angegeben werden, der mindestens size Byte groß ist. Dieser Puffer wird anstelle des momentanen Puffers verwendet. Wenn für buf NULL, angegeben wird, wird nur mode modifiziert. Bei der naechsten Schreib- oder Leseoperation wird ein neuer Puffer allokiert. Die Funktion setvbuf kann nur dann auf einen geöffneten Stream angewendet werden, wenn er nicht ``aktiv'' ist. Das heißt, vor der ersten Ein- bzw. Ausgabe oder unmittelbar nach einem fflush. Die anderen drei Funktionen sind im Endeffekt einfache Aliase für Aufrufe von setvbuf. Die Funktion setbuf entspricht genau dem folgendem Aufruf:

  setvbuf(stream, buf, buf ? _IOFBF : _IONBF, BUFSIZ); Die Funktion setbuffer ist die gleichen, bis auf die Tatsache, daß die Größe des Puffers vom Aufrufer bestimmt wird anstatt von der Voreinstellung BUFSIZ übernommen wird. Die Funktion setlinebuf entspricht genau dem folgendem Aufruf:

  setvbuf(stream, (char *)NULL, _IOLBF, 0);

KONFORM ZU
Die Funktionen setbuf und setvbuf sind konform zu ANSI C3.159-1989 (ANSI C).

Fehler
Die Funktionen setbuffer und setlinebuf sind keine portablen Versionen von BSD vor 4.2BSD, setbuf nutzt immer eine nichtoptimale Puffergröße und sollte deshalb vermieden werden. Es muß sichergestellt sein, daß der Puffer buf zu dem Zeitpunkt, zu dem der Stream stream geschlossen wird, noch exisitiert, was ebenfalls bei Programmende geschieht.

Im folgenden Beispiel wird der Stream stdin erst geschlossen wenn buf nicht mehr existiert. Dieser Code ist nicht zulässig:

#include <stdio.h>
int main()
{
    char buf[BUFSIZ];
    setbuf(stdin, buf);
    printf("Hello, world!\n");
    return 0;
}

SIEHE AUCH
fopen(3), fflush(3), fclose(3), fread(3), malloc(3), puts(3), printf(3).