This section describes how class filebuf should be used. #include <iostream.h> typedef long streamoff, streampos; class ios enum bin, tabexp}; // and lots of other class members, see ios ... }; #include <fstream.h> class filebuf : public streambuf static const int openprot; /* default protection for open*/ filebuf(); | |||
filebuf* | attach(int d); | ||
virtual int virtual streambuf* | overflow(int=EOF); setbuf(char* p, int len); | ||
}; | |||
This section describes how class filebuf should be used. #include <iostream.h> typedef long streamoff, streampos; class ios public: bin, tabexp}; // and lots of other class members, see ios ... }; #include <fstream.h> class filebuf : public streambuf static const int openprot; /* Standardschutzmodus für Öffnen*/ filebuf();
}; | |||||
filebufs specialize streambufs to use a file as source or sink of characters. Charactersare consumed by doing writes to the file, and are produced by doing reads. When thefile is seekable, a filebuf allows seeks. When the file permits reading and writing, thefilebuf permits both storing and fetching. No special action is required between gets and puts (unlike stdio). A filebuf that is connected to a file descriptor is said to be open. No protection mode is used for files in BS2000. The reserve area (or buffer, see sbufpub and sbufprot) is allocated automatically if it is not specified explicitly with a constructor or a call to setbuf(). filebufs can also be made unbuffered with certain arguments to the constructor or setbuf(), in which case each character is passed to the C runtime system for each read or write. Unbufferedinput/output is not as fast as buffered input/output. The get and put pointers into the reserve area are conceptually tied together and behave as a single pointer. Therefore,the descriptions below refer to a single get/put pointer. In the descriptions below, assume:
Constructorsfilebuf() Constructs an initially closed filebuf. filebuf(int d) Constructs a filebuf connected to file descriptor d. filebuf(int d, char * p, int len) Constructs a filebuf connected to file descriptor d, and initialized to use the reserve area starting at p and containing len bytes. If p is NULL, or len is zero or less, the filebuf is unbuffered. Members (non-virtual)filebuf * pfb=f.attach(int d) Connects f to an open file descriptor, d. attach() normally returns &f, but returns 0 if f is already open. filebuf * pfb=f.close() Flushes any waiting output, closes the file descriptor, and disconnects f. Unless an error occurs, f’s error state is cleared. close() returns &f unless errors occur, in which case it returns 0. Even if errors occur, close() leaves the file descriptor and f closed. int i=f.fd() Returns i, the file descriptor f is connected to. If f is closed, fd() returns EOF. int i=f.is_open() Returns non-zero when f is connected to a file descriptor, and zero otherwise. filebuf * pfb=f.open(char* name, int mode, int prot) Opens file name and connects f to it. If the file does not already exist, an attempt is made to create it, unless ios::nocreate or ios::in is specified in mode. The prot parameter is ignored under BS2000. Failure occurs if f is already open. On success,open() returns &f. If an error occurs it returns 0. The members of mode are bits that may be or’ed together. (Because the or’ing returns an int, open() takes an int rather than an open_mode argument.) The meanings of these bits in mode are described in detail in fstream. name can take any of the values described for the C library functions open() and fopen(). This name is passed to the C runtime system. Thus any kind of control (except for record-oriented input/output) is possible when opening files in C++. Please refer to section fstream for a list of possible values for name, and to the "C Library Functions" manual for more detailed information on file processing. Virtual membersint i=f.overflow(int c) Please refer to section sbufprot (streambuf::overflow()) for a general description. streampos sp=f.seekoff(streamoff off, ios::seek_dir dir, int mode) Moves the get/put pointer as designated by off and dir. It may fail if the file that f is attached to does not support seeking, or if the attempted motion is otherwise invalid(such as attempting to seek to a position before the beginning of file). off is interpreted as a count relative to the place in the file specified by dir as described insbufpub. mode is ignored. seekoff() returns sp, the new position, or EOF if a failure occurs. The position of the file after a failure is undefined. Relative seeks in text filesare invalid under BS2000 unless off = 0. streambuf * psb=f.setbuf(char * ptr, int len) Sets up the reserve area as len bytes beginning at ptr. If ptr is NULL or len is less than or equal to 0, f is unbuffered. setbuf() normally returns &f. However, if f is open and a buffer has been allocated, no changes are made to the reserve area or to thebuffering status, and setbuf() returns 0. int i=f.sync() Attempts to force the state of the get/put pointer of f to agree (be synchronized) withthe state of the file f.fd(). This means it may write characters to the file if some have been buffered for output or attempt to reposition (seek) the file if characters have been read and buffered for input. Normally, sync() returns 0, but it returns EOF if synchronization is not possible. However, sync() does not guarantee that the writes made were flushed to disk. Note Sometimes it is necessary to guarantee that certain characters are written together. To do this, the program should use setbuf() (or a constructor) to guarantee that the reserve area is at least as large as the number of characters that must be written together. It can then call sync(), then store the characters, then call sync() again. int i=f.underflow(); Please refer to section sbufprot (streambuf::underflow()) for a general description. | |||||
EXAMPLE | |||||
The following program tries to attach a variable of type filebuf to file descriptor 1, which is a cout, and then prints a message showing the success or failure of the attach(): #include <iostream.h>
#include <fstream.h>
#include <stdlib.h>
int main()
{
filebuf b; /* constructor with no parameters called */
if (b.attach(1))
{
static char str[] = "have attached filebuf b to file descriptor 1\n";
b.sputn(str, sizeof(str)-1);
}
else
{
cerr << "can't attach filebuf to file descriptor 1\n";
exit(1); /* error return */
}
return 0;
}
The result of executing the program is:
| |||||
BUGS | attach() and the constructors should test if the file descriptor they are given is open. There is no way to force atomic reads. | ||||
SEE ALSO | |||||
lseek() in the C runtime system | |||||