filebuf Puffer für die Datei-Ein-/Ausgabe

In diesem Abschnitt wird die Verwendung der Klasse filebuf beschrieben.

---

#include <iostream.h>

typedef long streamoff, streampos;

class ios
{

public:
enum seek_dir {beg, cur, end};
enum open_mode {in, out, ate, app, trunc, nocreate, noreplace,

bin, tabexp};

// sowie viele weitere Klassenelemente, siehe ios ...

};

#include <fstream.h>

class filebuf : public streambuf
{
public:

static const int openprot; /* Standardschutzmodus für Öffnen*/

filebuf();
˜filebuf();
filebuf(int d);
filebuf(int d, char* p, int len);

filebuf* filebuf* int int filebuf*	attach(int d); close(); fd(); is_open(); open(const char *name, int omode, int prot=openprot);
virtual int virtual streampos virtual streambuf* virtual int virtual int	overflow(int=EOF); seekoff(streamoff, ios::seek_dir, int omode); setbuf(char* p, int len); sync(); underflow();

};

---

filebuf ist ein Spezialfall der Klasse streambuf, wobei Dateien als Quelle oder Ziel für die Zeichenübertragung eingesetzt werden. Zeichen werden durch Schreiben in dieDatei "aufgebraucht" und durch Lesen aus der Datei "erzeugt". Wenn das Positionierenin einer Datei möglich ist, kann auch in dem filebuf-Objekt positioniert werden. Wenndie Datei das Lesen und Schreiben erlaubt, ermöglicht die Klasse filebuf sowohl dasSpeichern als auch die Entnahme von Zeichen. Zwischen Schreib- und Lesevorgängenist kein besonderer Aufruf erforderlich (im Gegensatz zu stdio). Ein filebuf-Objekt, dasmit einem Dateideskriptor verknüpft ist, wird als geöffnet bezeichnet. Dateien werden im BS2000 ohne Angabe eines Schutzmodus verwendet.

Der Reservierungsbereich (oder Puffer, siehe sbufpub und sbufprot) wird automatischzugewiesen, wenn mit einem Konstruktor oder beim Aufruf von setbuf() keine expliziteAngabe erfolgt. filebuf-Objekte können in einen nicht gepufferten Modus versetzt werden, indem an den Konstruktor oder setbuf() bestimmte Argumente übergeben werden.In diesem Fall wird bei jedem Lese- oder Schreibvorgang jedes Zeichen gleich an dasC-Laufzeitsystem durchgereicht. Dabei ist die nicht gepufferte Ein-/Ausgabe langsamerals die gepufferte. Die Zeiger get und put sind - für den Reservierungsbereich - miteinander verknüpft und verhalten sich wie ein einziger Zeiger. Die folgenden Beschreibungenbeziehen sich daher auf den einen kombinierten Zeiger.

Für die folgenden Beschreibungen wird angenommen, daß

• f vom Typ filebuf ist.
• mode eine int-Zahl ist, die den Öffnungsmodus (open_mode) darstellt.

Konstruktoren

filebuf()

Ein anfänglich geschlossenes filebuf-Objekt wird angelegt.

filebuf(int d)

Ein filebuf-Objekt, das mit dem Dateideskriptor d verknüpft ist, wird angelegt.

filebuf(int d, char * p, int len)

Ein mit dem Dateideskriptor d verknüpftes filebuf-Objekt wird angelegt. Das Objektist für die Verwendung des Reservierungsbereichs - beginnend bei p mit einer Längevon len byte - initialisiert. Wenn p gleich NULL oder wenn len kleiner oder gleich 0 ist, weist das filebuf-Objekt keine Pufferung auf.

Elementfunktionen (nicht virtuell)

filebuf * pfb=f.attach(int d)

f wird mit dem geöffneten Dateideskriptor d verknüpft. Die Funktion attach() liefertüblicherweise &f; der Wert 0 wird zurückgegeben, wenn f bereits geöffnet ist.

filebuf * pfb=f.close()

Auf die Ausgabe wartende Daten werden geschrieben, der Puffer gelöscht, der Dateideskriptor geschlossen und die Verknüpfung mit f gelöst. Sofern kein Fehler auftritt,wird der Fehlerstatus von f gelöscht. Die Funktion close() liefert &f, wenn keine Fehler auftreten. Anderenfalls wird der Wert 0 zurückgegeben. Auch beim Auftreten vonFehlern hinterläßt die Funktion close() den Dateideskriptor und f in geschlossenemZustand.

int i=f.fd()

Es wird der Dateideskriptor i geliefert, mit dem f verknüpft ist. Wenn f geschlossenist, liefert fd() den Wert EOF.

int i=f.is_open()

Ein Wert ungleich 0 wird geliefert, wenn f mit einem Dateideskriptor verknüpft ist.Anderenfalls wird der Wert 0 geliefert.

filebuf * pfb=f.open(char * name, int mode, int prot)

Die Datei name wird geöffnet und mit f verknüpft. Wenn die Datei noch nicht existiert,wird versucht, sie anzulegen, sofern in mode nicht ios::nocreate bzw. ios::in angegeben ist.
Der Parameter prot wird im BS2000 ignoriert.
Ein Fehler tritt auf, wenn f bereits geöffnet ist. Die Funktion open() liefert bei Erfolg f, im Fehlerfall den Wert 0.
Die Elemente von mode sind Bits, die durch eine ODER-Operation miteinander verknüpft werden können. (Da eine ODER-Operation einen int-Wert liefert, verwendet open() statt dem open_mode-Argument ein int-Argument). Die Bedeutung der einzelnen Bits in mode sind detailliert im Abschnitt fstream beschrieben.
Für den Dateinamen name sind alle Angaben möglich wie bei den C-Bibliotheksfunktionen open() bzw. fopen(). Dieser Name wird an das C-Laufzeitsystem weitergereicht. Damit sind alle Steuerungsmöglichkeiten (außer satzorientierte Ein-/Ausgabe)beim Öffnen einer Datei auch in C++ gegeben. Eine Auflistung der möglichen Angaben für name finden Sie im Abschnitt fstream , weitere detaillierte Informationen zur Dateiverarbeitung im Handbuch "C-Bibliotheksfunktionen".

Virtuelle Elementfunktionen

int i=f.overflow(int c)

Die Beschreibung der prinzipiellen Funktionsweise finden Sie im Abschnitt sbufprot(streambuf::overflow()).
Für filebuf-Objekte bedeutet das: Der Pufferinhalt wird in die dazugehörige Datei geschrieben, sofern f mit einer geöffneten Datei verbunden ist. Dadurch steht ein neuer put-Bereich zu Verfügung. Beim Auftreten eines Fehlers ist der Returnwert EOF.
Bei Erfolg wird 0 zurückgeliefert.

streampos sp=f.seekoff(streamoff off, ios::seek_dir dir, int mode)

Der Zeiger get/put wird entsprechend den Angaben in off und dir verschoben. Die Operation kann fehlschlagen, wenn die mit f verknüpfte Datei kein Positionieren unterstützt oder wenn die versuchte Verschiebung aus anderen Gründen ungültig ist (beispielsweise durch die Suche einer Position, die vor dem Dateibeginn liegt). off wird als Zählerwert interpretiert, der relativ zu der durch dir spezifizierten Position in derDatei liegt. Eine weitergehende Beschreibung finden Sie im Abschnitt zu sbufpub .
mode wird ignoriert. Die Funktion seekoff() liefert sp, die neue Position, oder EOF beim Auftreten eines Fehlers. Die Position in der Datei ist nach dem Auftreten eines Fehlers nicht definiert. Im BS2000 ist das relative Positionieren in Textdateien nur mitoff = 0 erlaubt.

streambuf * psb=f.setbuf(char * ptr, int len)

Der Reservierungsbereich wird, beginnend bei ptr, auf len byte gesetzt. f ist nichtgepuffert, wenn ptr gleich NULL oder len kleiner oder gleich 0 ist. Die Funktion setbuf() liefert üblicherweise &f. Wenn f bereits geöffnet ist und ein Puffer zugewiesen wurde, wird am Reservierungsbereich oder im Pufferungsstatus keine Änderungvorgenommen, und setbuf() liefert den Wert 0.

int i=f.sync()

Es wird versucht, den Status des Zeigers get/put von f mit dem Status der Datei f.fd() zu synchronisieren. Dies bedeutet, daß Zeichen in die Datei geschrieben werden, wenn diese in einem Puffer für die Ausgabe vorliegen, oder eine Repositionierung (seek) in der Datei versucht wird, wenn Zeichen gelesen wurden und die Eingabe gepuffert ist. Die Funktion sync() liefert üblicherweise den Wert 0. Wenn eineSynchronisation nicht möglich ist, wird der Wert EOF geliefert. sync() gewährleistet nicht, daß das "Leeren des Puffers" auf Diskette/Platte erfolgt.
Im BS2000 übergibt sync() den Pufferinhalt an das C-Laufzeitsystem. Die Synchronisation verwendet relatives Positionieren des C-Laufzeitsystem. Dies ist im BS2000 beiTextdateien nicht möglich. Die sync-Funktion kann deshalb nur auf Binärdateien angewendet werden.

Hinweis

Manchmal müssen Zeichen in einem Vorgang geschrieben werden. In diesem Fall sollte das Programm die Funktion setbuf() (oder einen Konstruktor) verwenden, damit der Reservierungsbereich groß genug ist, um alle zu schreibenden Zeichen aufzunehmen. Dann kann anschließend sync() aufgerufen werden, die Zeichen werden gespeichert, und es erfolgt ein erneuter Aufruf von sync().

int i=f.underflow();

Die Beschreibung der prinzipiellen Funktionsweise finden Sie im Abschnitt sbufprot (streambuf::underflow()).
Für filebuf-Objekte bedeutet das:
Wenn der get-Bereich leer ist, wird aus der dazugehörigen Datei gelesen, sofern f mit einer geöffneten Datei verbunden ist (auffüllen des get-Bereiches). Bei Erfolg wird das nächste Zeichen zurückgeliefert.
Beim Auftreten eines Fehlers ist der Returnwert EOF.

BEISPIEL

Das folgende Programm versucht, dem Dateideskriptor 1 (entspricht cout) eine Variable des Typs filebuf zuzuordnen. Anschließend wird eine Meldung ausgegeben, die den Erfolg oder Mißerfolg von attach() anzeigt:

#include <iostream.h>
#include <fstream.h>
#include <stdlib.h>
int main()
{
  filebuf b;     /* Konstruktor ohne Parameter wird aufgerufen */
  if (b.attach(1))
  {
    static char str[] = "filebuf b wurde mit Dateideskriptor 1 verknuepft\n";
    b.sputn(str, sizeof(str)-1);
  }
  else
  {
    cerr << "filebuf kann nicht mit Dateideskriptor 1 verknuepft werden\n";
    exit(1);      /* Rückgabe bei Fehler */
  }
  return 0;
}

Das Ergebnis der Programmausführung ist:

filebuf b wurde mit Dateideskriptor 1 verknuepft
%  CCM0998 Verbrauchte CPU-Zeit: 0.0003 Sekunden

BESONDERHEITEN

Die Funktion attach() und die Konstruktoren sollten prüfen, ob der übergebene Dateideskriptor geöffnet ist.

Unteilbare Lesevorgänge (atomic) können nicht erzwungen werden.

SIEHE AUCH 

fstream , sbufprot , sbufpub

lseek() im C-Laufzeitsystem