filebuf Buffer for file input/output

	This section describes how class filebuf should be used. #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}; // and lots of other class members, see ios ... }; #include <fstream.h> class filebuf : public streambuf { public: static const int openprot; /* default protection for open*/ 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();
	};

This section describes how class filebuf should be used.

---

#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};

// and lots of other class members, see 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();

};

---

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:

• f is a filebuf.
• mode is an int representing an open_mode.

Constructors

filebuf()

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 members

int i=f.overflow(int c)

Please refer to section sbufprot (streambuf::overflow()) for a general description.
For filebufs this means:
The contents of the buffer is written to the associated file if f is attached to an openfile. Thus a new put area becomes available.
On error, EOF is returned.
On success, 0 is returned.

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.
In BS2000, sync() passes the contents of the buffer to the C runtime system.
Synchronization uses relative seeks of the C runtime system. This is not possible fortext files under BS2000. Therefore, the sync function can only be used for binary files.

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.
For filebufs this means:
When the get area is empty, the associated file is read if f is attached to an open file (padding the get area). On success, the next character is returned.
On error, EOF is returned.

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:

have attached filebuf b to file descriptor 1

%  CCM0998 CPU time used: 0.0003 seconds

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

fstream, sbufprot, sbufpub

 lseek() in the C runtime system