streambuf_pub(3C++)
streambuf_pub --
public interface of character buffering class
Synopsis
#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 } ;
// and lots of other stuff ... See ios(3C++)
} ;
class streambuf {
public :
int in_avail();
int out_waiting();
int sbumpc();
streambuf* setbuf(char* ptr, int len);
streampos seekpos(streampos, int =ios::in|ios::out);
streampos seekoff(streamoff, seek_dir, int =ios::in|ios::out);
int sgetc();
int sgetn(char* ptr, int n);
int snextc();
int sputbackc(char);
int sputc(int c);
int sputn(const char* s, int n);
void stossc();
virtual int sync();
};
Description
The streambuf class supports buffers into which
characters can be inserted (put) or from which characters can be
fetched (gotten).
Abstractly, such a buffer is a sequence of characters together with one or
two pointers (a get and/or a put pointer) that define
the location at which characters are to be inserted or fetched.
The pointers should be thought of as pointing between characters
rather than at them.
This makes it easier to understand the
boundary conditions (a pointer before the first character or after
the last).
Some of the effects of getting and putting are defined
by this class but most of the details are left to specialized
classes derived from streambuf.
(See
filebuf(3C++),
strstreambuf(3C++),
and
stdiobuf(3C++).)
Classes derived from streambuf vary in their
treatments of the get and put pointers.
The simplest are unidirectional buffers which permit only gets or
only puts.
Such classes serve as pure sources (producers) or sinks (consumers)
of characters.
Queuelike buffers (e.g., see
strstream(3C++)
and
strstreambuf(3C++))
have a put and a get pointer which move independently of each other.
In such buffers characters that are stored are held (i.e., queued)
until they are later fetched.
Filelike buffers (e.g., filebuf, see
filebuf(3C++))
permit both gets and puts but have only a single pointer.
(An alternative description is that the get and put pointers are tied
together so that when one moves so does the other.)
Most streambuf member functions are organized into two phases.
As far as possible, operations are performed inline by storing into
or fetching from arrays (the get area and the put area,
which together form the reserve area, or buffer).
From time to time, virtual functions are called to
deal with collections of characters in the get and put areas.
That is, the virtual functions are called to fetch more characters
from the ultimate producer or to flush a collection of characters
to the ultimate consumer.
Generally the user of a streambuf does not have to know
anything about these
details, but some of the public members pass back information
about the state of the areas.
Further detail about these areas is provided in
streambuf_prot(3C++),
which describes the protected interface.
The public member functions of the streambuf class
are described below.
In the following descriptions assume:
-- i, n, and len are ints.
-- c is an int. It always holds a ``character''
value or EOF. A ``character'' value is always positive
even when char is normally sign extended.
-- sb and sb1 are streambuf*s.
-- ptr is a char*.
-- off is a streamoff.
-- pos is a streampos.
-- dir is a seek_dir.
-- mode is an int representing an open_mode.
Public member functions:
i=sb->in_avail()-
Returns the number of characters that are immediately available in the
get area for fetching.
i characters may be fetched with a guarantee that no errors will
be reported.
i=sb->out_waiting()-
Returns the number of characters in the put area that have not
been consumed (by the ultimate consumer).
c=sb->sbumpc()-
Moves the get pointer forward one character and returns the
character it moved past.
Returns EOF if the get pointer is currently at the end of the
sequence.
pos=sb->seekoff(off, dir, mode)-
Repositions the get and/or put pointers.
mode specifies whether the put pointer (ios::out bit set) or
the get pointer (ios::in bit set) is to be modified.
Both bits may be set in which case both pointers should be affected.
off is interpreted as a byte offset.
(Notice that it is a signed quantity.)
The meanings of possible values of dir are
ios::beg-
The beginning of the stream.
ios::cur-
The current position.
ios::end-
The end of the stream (end of file.)
Not all classes derived from streambuf support repositioning.
seekoff() will return EOF if the class does not support
repositioning.
If the class does support repositioning, seekoff() will return the new
position or EOF on error.
pos=sb->seekpos(pos, mode)-
Repositions the streambuf get and/or put pointer to pos.
mode specifies which pointers are affected as for seekoff().
Returns pos (the argument) or EOF if the class does
not support repositioning or an error occurs.
In general a streampos should be treated as a ``magic cookie''
and no arithmetic should be performed on it.
Two particular values have special meaning:
streampos(0)-
The beginning of the file.
streampos(EOF)-
Used as an error indication.
c=sb->sgetc()-
Returns the character after the get pointer.
Contrary to what most people expect from the name
IT DOES NOT MOVE THE GET POINTER.
Returns EOF if there is no character available.
sb1=sb->setbuf(ptr, len, i)-
Offers the len bytes starting at ptr as the reserve area.
If ptr is null or len is zero or less, then an unbuffered
state is requested.
Whether the offered area is used, or a request for unbuffered
state is honored depends on details of the derived class.
setbuf() normally returns sb, but if it does not
accept the offer or honor the request, it returns 0.
i=sb->sgetn(ptr, n)-
Fetches the n characters following the get pointer and copies
them to the area starting at ptr.
When there are fewer than n characters left before the end of
the sequence sgetn() fetches whatever characters remain.
sgetn() repositions the get pointer following the fetched
characters and returns the number of characters fetched.
c=sb->snextc()-
Moves the get pointer forward one character
and returns the character following the new position.
It returns EOF if the pointer
is currently at the end of the sequence or is at the end of
the sequence after moving forward.
i=sb->sputbackc(c)-
Moves the get pointer back one character.
c must be the current content of the sequence just before the
get pointer.
The underlying mechanism may simply back up the get pointer or may
rearrange its internal data structures so the c is saved.
Thus the effect of sputbackc() is undefined if c is not
the character before the get pointer.
sputbackc() returns EOF when it fails.
The conditions under which it can fail depend on the details of
the derived class.
i=sb->sputc(c)-
Stores c after the put pointer, and moves the put pointer past
the stored character; usually this extends the sequence.
It returns EOF when an error occurs.
The conditions
that can cause errors depend on the derived class.
i=sb->sputn(ptr, n)-
Stores the n characters starting at ptr after the put pointer
and moves the put pointer past them.
sputn() returns i, the number of characters stored successfully.
Normally i is n, but it may be less when errors occur.
sb->stossc()-
Moves the get pointer forward one character. If the pointer started at the
end of the sequence this function has no effect.
i=sb->sync()-
Establishes consistency between the internal data structures and the
external source or sink.
The details of this function depend on the derived class.
Usually this ``flushes'' any characters that have been stored
but not yet consumed, and ``gives back'' any characters that
may have been produced but not yet fetched.
sync() returns EOF to indicate errors.
Notices
setbuf does not really belong in the public interface.
It is there for compatibility with the stream package.
Requiring the program to provide the previously fetched character to
sputback is probably a botch.
References
ios(3C++),
istream(3C++),
ostream(3C++),
streambuf_prot(3C++)
© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 25 April 2004