setvbuf

Nach oben zu stdio.h - Index

Header-Datei

stdio.h

Kategorie

Eingabe-/Ausgaberoutinen

Prototyp

int setvbuf(FILE *stream, char *buf, int type, size_t size);

Beschreibung

Weist einem Stream einen Puffer zu.

setvbuf bewirkt, dass der Puffer buf statt eines automatisch zugewiesenen Puffers für die gepufferte Ein-/Ausgabe verwendet wird. Die Funktion wird verwendet, nachdem der angegebene Stream geöffnet wurde.

Ist buf NULL, wird ein mit malloc zugewiesener Puffer verwendet, wobei der Parameter size die Puffergröße angibt. Der Puffer wird beim Schließen automatisch freigegeben. Der Parameter size gibt die Puffergröße an und muss größer Null sein.

Der Parameter size ist durch die Konstante UINT_MAX eingeschränkt, die in limits.h definiert ist.

Sind stdin und stdout nicht umgeleitet, dann sind sie nicht gepuffert; andernfalls sind sie voll gepuffert. Nicht gepuffert bedeutet, dass die in einen Stream geschriebenen Zeichen sofort in die Datei oder das Gerät ausgegeben werden, während gepuffert bedeutet, dass die Zeichen zunächst gesammelt und dann als Block geschrieben werden.

• Der Parameter type kann einen der folgenden Werte annehmen:

_IOFBF	voll gepufferte Datei. Wenn der Puffer leer ist, versucht die nächste Eingabeoperation, den gesamten Puffer zu füllen. Bei der Ausgabe wird der Puffer vollständig gefüllt, bevor irgendwelche Daten in die Datei geschrieben werden.
_IOLBF	zeilengepufferte Datei. Wenn der Puffer leer ist, versucht die nächste Eingabeoperation ebenfalls, den gesamten Puffer zu füllen. Bei der Ausgabe wird jedoch der Pufferinhalt in die Datei übertragen, sobald ein Zeilenvorschubzeichen in die Datei geschrieben wird.
_IONBF	nicht gepufferte Datei Die Parameter buf und size werden ignoriert. Jede Eingabeoperation liest direkt aus der Datei und jede Ausgabeoperation schreibt die Daten direkt in die Datei.

Häufige Ursache eines Fehlers ist die Zuweisung des Puffers in Form einer automatischen (lokalen) Variablen, wobei dann vergessen wird, die Datei vor dem Verlassen der Funktion, in der der Puffer deklariert wurde, zu schließen.

Rückgabewert

Wenn erfolgreich, gibt setvbuf 0 zurück.

Tritt ein Fehler auf (weil ein ungültiger Wert für type oder size angegeben wurde oder nicht genügend Speicher für die Reservierung des Puffers verfügbar ist) wird ein Wert ungleich Null zurückgegeben.

Beispiel

 #include <stdio.h>
 int main(void)
 {
    FILE *input, *output;
    char bufr[512];
    input = fopen("file.in", "r+b");
    output = fopen("file.out", "w");
    /* Eingabe-Stream, der einen eigenen Zeichenpuffer
       für minimale Plattenzugriffe einrichten */
 if (setvbuf(input, bufr, _IOFBF, 512) != 0)
       printf("failed to set up buffer for input file\n");
    else
       printf("failed to set up buffer for input file\n");
    /* Zeilengepufferten Ausgabe-Stream einrichten, der einen über
       einen indirekten Aufruf von malloc reservierten Puffer verwendet */
    if (setvbuf(output, NULL, _IOLBF, 132) != 0)
       printf("failed to set up buffer for output file\n");
    else
       printf("buffer set up for output file\n");
    /* Hier folgen Ein-Ausgabeoperationen */
    /* Dateien schließen */
    fclose(input);
    fclose(output);
    return 0;
 }

Portabilität

POSIX	Win32	ANSI C	ANSI C++
+	+	+	+